Prerelease Versioning Added to PowerShellGet and PowerShell Gallery

J. Keith Bankston

With the release of PowerShellGet 1.6.0, PowerShellGet cmdlets and the PowerShell Gallery have added support for prerelease strings for prerelease versions of modules and scripts. You can now publish items to the PowerShell Gallery with a version like 1.0.0-alpha, and you can download items identified as a prerelease. Items can be filtered using prerelease version strings, in both the Gallery UI and via Find-* cmdlets.
Before this feature, if publishers wished to publish a prerelease version of an item, they had to use a version lower than 1.0.0 (ex. 0.0.1). This meant it was not possible to publish a prerelease version of a 2.0.0 item. The other workaround was to change the name of the item to contain the word “prerelease” (ex. MyAwesomeModule-Prerelease), but that required code changes for users when the production version was ready, because it changed the name of the item. 
Now, users can mark their items as prerelease, following the SemVer v1.0.0 guidelines, without affecting the item name or constraints on the version.
Publishers simply add the prerelease string (ie. the part that comes after “2.0.0”) in the metadata, and the version will be considered prerelease. For example:
@{
   ModuleVersion = '2.0.0'
   #---
      PrivateData = @{
         PSData = @{
            Prerelease = '-alpha'
      }
   }
}
To acquire or interact with prerelease items using the PowerShellGet cmdlets, users must add the -AllowPrerelease flag. For example, to find prerelease versions of a module:
   PS:> Find-Module PSReadline -AllowPrerelease -Allversions
To install a prerelease version from the gallery:
   PS:> Install-Module PSReadline -RequiredVersion 2.0.0-beta1 -AllowPrerelease
   PS:> # Note that you may need to add -SkipPublisherCheck for this update to proceed.

To update a module to a prerelease version from the gallery:

   PS:> Update-Module PSReadline -RequiredVersion 2.0.0-beta1 -AllowPrerelease
   PS:> # Updates to 2.0.0-beta1. You may need to add -SkipPublisherCheck.
The PowerShell Gallery UI has also been updated to support prerelease items. In the Items page, a new dropdown under “Filter By” gives control over whether or not to list prerelease items. The options available are “Include Prerelease”, and “Stable Only”.

PowerShell Gallery prerelease filter

Additional changes appear on the pages for individual items. If an item is a prerelease, there will be a banner at the top of the page stating that this is a prerelease version:

PowerShell Gallery prerelease item banner

The following banner was added to show that the current item is the latest stable version of an item, but a prerelease item exists with a higher version:

PowerShell last stable item banner

Finally, the item history on the same page has been updated to show the latest stable (or non-prerelease) version available, as shown below:

PowerShell Gallery prerelease item history

Some important things to note:
  • If -AllowPrerelease is not specified, the behavior of the cmdlets is the same as one would see with older versions of PowerShellGet: no prerelease versions will be returned. This ensures these changes are backwards compatible with previous PowerShellGet versions.
  • This change only affects the PowerShellGet cmdlets and the PowerShell Gallery. As of the writing of this blog, PowerShell does not support prerelease strings in version identifiers, so prerelease strings are provided as a separate element in the module manifest.
  • There are limitations on what the prerelease string can contain, see the Documentation for more details. 
  • Prerelease support follows the SemVer v1.0.0 guidelines. We chose to align with SemVer 1.0.0 to maintain parity with the current NuGet server used by many of our customers as an on-premise gallery.
To start using prerelease versions in your modules and scripts with the PowerShell Gallery, update to the latest PowerShellGet moduleYou must install the update in order to use the -AllowPrerelease flag, which is required for finding or downloading any prerelease items in the PowerShell Gallery. 
We would love to hear your feedback on this new feature. Please submit any questions or comments in either the PowerShellGet GiHub repo issues , or the PowerShell Gallery feedback area on UserVoice.

1 comment

Discussion is closed. Login to edit/delete existing comments.

Feedback usabilla icon