Prerelease Build Support for Pode

[mdaneri]

Summary

This PR enhances Pode's build process to support prerelease versions (e.g., alpha, beta) by modifying the build script (pode.build.ps1), module manifest (.psd1), and module script (.psm1). Additionally, it introduces a Version.json file for managing versioning dynamically and adds a new -PersistVersion parameter to save the provided version into Version.json.

Changes Introduced

1. Prerelease Versioning Support

• Added the -Prerelease parameter to pode.build.ps1, allowing versions to follow semantic versioning conventions (e.g., alpha.1, beta.2).
• Ensures that prerelease versions are correctly applied in the module metadata and build artifacts.

2. Version Management via Version.json

• Introduced a Version.json file that allows specifying the version and prerelease identifier.
• Ensures that after a build is completed, the exact version used for that build is recorded in the source code, making it clear which version the repository is at.
• The build script automatically reads from Version.json if no explicit -Version or -Prerelease parameters are provided.
• Example content of Version.json:

  {
      "Version": "2.13.0",
      "Prerelease": "alpha.3"
  }

3. New -PersistVersion Parameter

• Added a new parameter, -PersistVersion, which allows saving the provided -Version and -Prerelease values into Version.json.
• Ensures consistency across builds by persisting the specified version unless explicitly overridden.
• Why this matters: Previously, there was no way to determine the current version of the source code after a build. This change makes the version explicit and trackable.
• Usage Example:

  Invoke-Build -Task Build -Version '2.13.0' -Prerelease 'beta.1' -PersistVersion

  (This updates Version.json to store 2.13.0-beta.1 for future reference.)
• If -PersistVersion is used without specifying -Version, an error will be thrown:

  Write-Error "The -PersistVersion parameter requires the -Version parameter to be specified."

4. Updates to .psm1 and .psd1 for Prerelease Handling

• Adjusted the module manifest (.psd1) to support dynamic versioning for prerelease builds.
• Updated .psm1 to ensure that the correct versioning information is reflected when loading the module.

Example Usage

Setting a Prerelease Version Explicitly

Invoke-Build -Task Build -Version '2.13.0' -Prerelease 'alpha.3'

Using Version.json for Automatic Versioning

Invoke-Build -Task Build

(This will read from Version.json if available.)

Saving the Version to Version.json

Invoke-Build -Task Build -Version '2.13.0' -Prerelease 'beta.1' -PersistVersion

(This updates Version.json to persist the specified version for future builds.)

Why This Change?

• Ensures consistency in Pode's versioning by aligning with semantic versioning best practices.
• Improves developer workflow by making version management easier through Version.json.
• Makes the version explicit in the source code, removing ambiguity about what version the repository is at after a build.
• Enables smoother prerelease testing by allowing different prerelease iterations (e.g., alpha.1, beta.2).
• Allows automated version persistence for more predictable builds.

Testing

• Verified that builds correctly apply prerelease versions.
• Tested versioning behavior with and without Version.json.
• Ensured .psm1 and .psd1 changes do not break module loading.
• Tested -PersistVersion to confirm it correctly writes to Version.json.
• Ensured an error is thrown if -PersistVersion is used without -Version.