Skip to content

Commit 1e0c256

Browse files
J. Keith Bankston [MSFT]Sean Wheeler
J. Keith Bankston [MSFT]
authored and
Sean Wheeler
committed
Adding PreRelease versioning info for PSGallery & PSGet (#1903)
* PowerShellGet PreRelease Support Adding descriptive doc for pre-release versioning support * Correcting typos in pre-release doc Minor typos and case issues fixed * Updated prerelease info based on feedback Mostly cosmetic updates. Functional change: added line 28, stating we only support 3-segment module versions. * Adding prerelease to module install update find save commands * Updating PSGet -Script commands for Prerelease support * Hyphen listed as optional rather than preferred in Prereleasestring * Minor corrections from Rebro review * Addressing @sdwheeler feedback on links and double slashes * Fixing broken link * Update PreReleaseScript.md
1 parent 877c2cc commit 1e0c256

11 files changed

+484
-267
lines changed

‎gallery/psget/module/PreReleaseModule.md

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
---
2+
ms.date: 2017-09-26
3+
contributor: keithb
4+
ms.topic: reference
5+
keywords: gallery,powershell,cmdlet,psget
6+
title: PrereleaseModule
7+
---
8+
9+
# Prerelease Module Versions
10+
Starting with version 1.5.0, PowerShellGet and the PowerShell Gallery provide support for tagging versions greater than 1.0.0 as a prerelease. Prior to this feature, prerelease items were limited to having a version beginning with 0. The goal of these features is to provide greater support for [SemVer v1.0.0](http://semver.org/spec/v1.0.0.html) versioning convention without breaking backwards compatibility with PowerShell versions 3 and above, or existing versions of PowerShellGet. This topic focuses on the module-specific features. The equivalent features for scripts are in the [Prerelease Versions of Scripts](../script/PrereleaseScript.md) topic. Using these features, publishers can identify a module or script as version 2.5.0-alpha, and later release a production-ready version 2.5.0 that supersedes the prerelease version.
11+
12+
At a high level, the prerelease module features include:
13+
14+
* Adding a Prerelease string to the PSData section of the module manifest identifies the module as a prerelease version.
15+
When the module is published to the PowerShell Gallery, this data is extracted from the manifest, and used to identify prerelease items.
16+
* Acquiring prerelease items requires adding -AllowPrerelease flag to the PowerShellGet commands Find-Module, Install-Module, Update-Module, and Save-Module.
17+
If the flag is not specified, prerelease items will not be shown.
18+
* Module versions displayed by Find-Module, Get-InstalledModule, and in the PowerShell Gallery will be displayed as a single string with the Prerelease string appended, as in 2.5.0-alpha.
19+
20+
Details for the features are included below.
21+
22+
These changes do not affect the module version support that is built into PowerShell, and are compatible with PowerShell 3.0, 4.0, and 5.
23+
24+
## Identifying a module version as a prerelease
25+
26+
PowerShellGet support for prerelease versions requires the use of two fields within the Module Manifest:
27+
28+
* The ModuleVersion included in the module manifest must be a 3-part version if a prerelease version is used, and must comply with existing PowerShell versioning. The version format would be A.B.C, where A, B, and C are all integers.
29+
* The Prerelease string is specified in the module manifest, in the PSData section of PrivateData.
30+
Detailed requirements on the Prerelease string are below.
31+
32+
An example section of a module manifest that defines a module as a prerelease would look like the following:
33+
```powershell
34+
@{
35+
ModuleVersion = '2.5.0'
36+
#---
37+
PrivateData = @{
38+
PSData = @{
39+
Prerelease = 'alpha'
40+
}
41+
}
42+
}
43+
```
44+
45+
The detailed requirements for Prerelease string are:
46+
47+
* Prerelease string may only be specified when the ModuleVersion is 3 segments for Major.Minor.Build. This aligns with SemVer v1.0.0.
48+
* A hyphen is the delimiter between the Build number and the Prerelease string. A hyphen may be included in the Prerelease string as the first character, only.
49+
* The Prerelease string may contain only ASCII alphanumerics [0-9A-Za-z-]. It is a best practice to begin the Prerelease string with an alpha character, as it will be easier to identify that this is a prerelease version when scanning a list of items.
50+
* Only SemVer v1.0.0 prerelease strings are supported at this time. Prerelease string __must not__ contain either period or + [.+], which are allowed in SemVer 2.0.
51+
* Examples of supported Prerelease string are: -alpha, -alpha1, -BETA, -update20171020
52+
53+
__Prerelease versioning impact on sort order and installation folders__
54+
55+
Sort order changes when using a prerelease version, which is important when publishing to the PowerShell Gallery, and when installing modules using PowerShellGet commands.
56+
If the Prerelease string is specified for two modules, the sort order is based on the string portion following the hyphen. So, version 2.5.0-alpha is less than 2.5.0-beta, which is less than 2.5.0-gamma.
57+
If two modules have the same ModuleVersion, and only one has a Prerelease string, the module without the Prerelease string is assumed to be the production-ready version and will be sorted as a greater version than the prerelease version (which includes the Prerelease string).
58+
As an example, when comparing releases 2.5.0 and 2.5.0-beta, the 2.5.0 version will be considered the greater of the two.
59+
60+
When publishing to the PowerShell Gallery, by default the version of the module being published must have a greater version than any previously-published version that is in the PowerShell Gallery.
61+
62+
## Finding and acquiring prerelease items using PowerShellGet commands
63+
64+
Dealing with prerelease items using PowerShellGet Find-Module, Install-Module, Update-Module, and Save-Module commands requires adding the -AllowPrerelease flag.
65+
If -AllowPrerelease is specified, prerelease items will be included if they are present.
66+
If -AllowPrerelease flag is not specified, prerelease items will not be shown.
67+
68+
The only exceptions to this in the PowerShellGet module commands are Get-InstalledModule, and some cases with Uninstall-Module.
69+
70+
* Get-InstalledModule always will automatically show the prerelease information in the version string for modules.
71+
* Uninstall-Module will by default uninstall the most recent version of a module, if __no version__ is specified. That behavior has not changed. However, if a prerelease version is specified using -RequiredVersion, -AllowPrerelease will be required.
72+
73+
## Examples
74+
```powershell
75+
# Assume the PowerShell Gallery has TestPackage module versions 1.8.0 and 1.9.0-alpha. If -AllowPrerelease is not specified, only version 1.8.0 will be returned.
76+
C:\windows\system32> find-module TestPackage
77+
78+
Version Name Repository Description
79+
------- ---- ---------- -----------
80+
1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe...
81+
82+
C:\windows\system32> find-module TestPackage -AllowPrerelease
83+
84+
Version Name Repository Description
85+
------- ---- ---------- -----------
86+
1.9.0-alpha TestPackage PSGallery Package used to validate changes to the PowerShe...
87+
88+
# To install a prerelease, always specify -AllowPrerelease. Specifying a prerelease version string is not sufficient.
89+
90+
C:\windows\system32> Install-module TestPackage -RequiredVersion 1.9.0-alpha
91+
PackageManagement\Find-Package : No match was found for the specified search criteria and module name 'TestPackage'.
92+
Try Get-PSRepository to see all available registered module repositories.
93+
At C:\Program Files\WindowsPowerShell\Modules\PowerShellGet\1.6.0\PSModule.psm1:1455 char:3
94+
+ PackageManagement\Find-Package @PSBoundParameters | Microsoft ...
95+
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
96+
+ CategoryInfo : ObjectNotFound: (Microsoft.Power...ets.FindPackage:FindPackage) [Find-Package], Exceptio
97+
n
98+
+ FullyQualifiedErrorId : NoMatchFoundForCriteria,Microsoft.PowerShell.PackageManagement.Cmdlets.FindPackage
99+
100+
# The previous command failed because -AllowPrerelease was not specified.
101+
# Adding -AllowPrerelease will result in success.
102+
103+
C:\windows\system32> Install-module TestPackage -RequiredVersion 1.9.0-alpha -AllowPrerelease
104+
C:\windows\system32> Get-InstalledModule TestPackage
105+
106+
Version Name Repository Description
107+
------- ---- ---------- -----------
108+
1.9.0-alpha TestPackage PSGallery Package used to validate changes to the PowerShe...
109+
110+
```
111+
112+
Side-by-side installation of versions of a module that differ only due to the prerelease specified is not supported.
113+
When installing a module using PowerShellGet, different versions of the same module are installed side-by-side by creating a folder name using the ModuleVersion.
114+
The ModuleVersion, without the prerelease string, is used for the folder name.
115+
If a user installs MyModule version 2.5.0-alpha, it will be installed to the MyModule\2.5.0 folder.
116+
If the user then installs 2.5.0-beta, the 2.5.0-beta version will __over-write__ the contents of the folder MyModule\2.5.0.
117+
One advantage to this approach is that there is no need to un-install the prerelease version after installing the production-ready version.
118+
The example below shows what to expect:
119+
120+
121+
``` powershell
122+
C:\windows\system32> Get-InstalledModule TestPackage -AllVersions
123+
124+
Version Name Repository Description
125+
------- ---- ---------- -----------
126+
1.9.0-alpha TestPackage PSGallery Package used to validate changes to the PowerShe...
127+
1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe...
128+
1.1.3.2 TestPackage PSGallery Package used to validate changes to the PowerShe...
129+
130+
C:\windows\system32> find-module TestPackage -AllowPrerelease
131+
132+
Version Name Repository Description
133+
------- ---- ---------- -----------
134+
1.9.0-beta TestPackage PSGallery Package used to validate changes to the PowerShe...
135+
136+
C:\windows\system32> Update-Module TestPackage -AllowPrerelease
137+
C:\windows\system32> Get-InstalledModule TestPackage -AllVersions
138+
139+
Version Name Repository Description
140+
------- ---- ---------- -----------
141+
1.9.0-beta TestPackage PSGallery Package used to validate changes to the PowerShe...
142+
1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe...
143+
1.1.3.2 TestPackage PSGallery Package used to validate changes to the PowerShe...
144+
145+
```
146+
147+
Uninstall-Module will remove the latest version of a module when -RequiredVersion is not supplied.
148+
If -RequiredVersion is specified, and is a prerelease, -AllowPrerelease must be added to the command.
149+
150+
``` powershell
151+
C:\windows\system32> Get-InstalledModule TestPackage -AllVersions
152+
153+
Version Name Repository Description
154+
------- ---- ---------- -----------
155+
2.0.0-alpha1 TestPackage PSGallery Package used to validate changes to the PowerShe...
156+
1.9.0-beta TestPackage PSGallery Package used to validate changes to the PowerShe...
157+
1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe...
158+
1.1.3.2 TestPackage PSGallery Package used to validate changes to the PowerShe...
159+
160+
C:\windows\system32> Uninstall-Module TestPackage -RequiredVersion 1.9.0-beta
161+
Uninstall-Module : The '-AllowPrerelease' parameter must be specified when using the Prerelease string in
162+
MinimumVersion, MaximumVersion, or RequiredVersion.
163+
At line:1 char:1
164+
+ Unnstall-Module TestPackage -RequiredVersion 1.9.0-beta
165+
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
166+
+ CategoryInfo : InvalidArgument: (:) [Uninstall-Module], ArgumentException
167+
+ FullyQualifiedErrorId : AllowPrereleaseRequiredToUsePrereleaseStringInVersion,Uninnstall-Module
168+
169+
170+
171+
C:\windows\system32> Uninstall-Module TestPackage -RequiredVersion 1.9.0-beta -AllowPrerelease
172+
C:\windows\system32> Get-InstalledModule TestPackage -AllVersions
173+
174+
Version Name Repository Description
175+
------- ---- ---------- -----------
176+
2.0.0-alpha1 TestPackage PSGallery Package used to validate changes to the PowerShe...
177+
1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe...
178+
1.1.3.2 TestPackage PSGallery Package used to validate changes to the PowerShe...
179+
180+
C:\windows\system32> Uninstall-Module TestPackage
181+
C:\windows\system32> Get-InstalledModule TestPackage -AllVersions
182+
183+
Version Name Repository Description
184+
------- ---- ---------- -----------
185+
1.8.0 TestPackage PSGallery Package used to validate changes to the PowerShe...
186+
1.1.3.2 TestPackage PSGallery Package used to validate changes to the PowerShe...
187+
188+
189+
```
190+
191+
192+
193+
## More details
194+
### [Prerelease Script Versions](../script/PrereleaseScript.md)
195+
### [Find-Module](./psget_find-module.md)
196+
### [Install-Module](./psget_install-module.md)
197+
### [Save-Module](./psget_save-module.md)
198+
### [Update-Module](./psget_update-module.md)
199+
### [Get-InstalledModule](./psget_get-installedmodule.md)
200+
### [UnInstall-Module](./psget_uninstall-module.md)

‎gallery/psget/module/psget_find-module.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,9 @@ Find-Module -Name PSReadline -MinimumVersion 1.0.0.12 -MaximumVersion 1.0.0.13
6363
# Find a module with exact version
6464
Find-Module -Name AzureRM -RequiredVersion 1.3.2
6565
66+
# Find a module with a specific prerelease version
67+
Find-Module -Name AzureRM -RequiredVersion 1.3.2-alpha -AllowPrerelease
68+
6669
# Find a module from the specified repository
6770
Find-Module -Name Contoso -Repository MyLocalRepo
6871

‎gallery/psget/module/psget_install-module.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,12 @@ Install-Module -Name ContosoServer -MinimumVersion 1.0
7777
# Install a specific version of a module
7878
Install-Module -Name ContosoServer -RequiredVersion 1.1.3
7979
80+
# Install a specific prerelease version of a module
81+
Install-Module -Name ContosoServer -RequiredVersion 1.1.3-alpha -AllowPrerelease
82+
83+
# Install the latest version of a module by name, including prelrelease versions if one exists
84+
Install-Module -Name ContosoServer -AllowPrerelease
85+
8086
# Install the latest version of a module to $home\Documents\WindowsPowerShell\Modules.
8187
Install-Module -Name ContosoServer -Scope CurrentUser
8288

‎gallery/psget/module/psget_save-module.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,5 +50,14 @@ Find-Command -Name "Get-NestedRequiredModule4" -Repository "INT" | Save-Module -
5050
# Save the role capability modules by piping the Find-RoleCapability output to Save-Module cmdlet.
5151
Find-RoleCapability -Name Maintenance,MyJeaRole | Save-Module -Path C:\MyModulesPath
5252
53+
54+
# Save a specific prerelease version of a module to C:\MySavedModuleLocation
55+
Save-Module -Name ContosoServer -RequiredVersion 1.1.3-alpha -Path C:\MySavedModuleLocation -AllowPrerelease
56+
57+
# Install the latest version of a module by name, including prelrelease versions if one exists
58+
Install-Module -Name ContosoServer -Path C:\MySavedModuleLocation -AllowPrerelease
59+
60+
61+
5362
```
5463

‎gallery/psget/module/psget_update-module.md

Lines changed: 45 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -39,38 +39,38 @@ Get-Command -Name Update-Module -Module PowerShellGet -Syntax
3939
## Example commands
4040

4141
```powershell
42-
PS C:\\windows\\system32> Update-Module -Name ContosoServer -RequiredVersion 1.5
43-
PS C:\\windows\\system32> Get-Module -ListAvailable -Name ContosoServer | Format-List Name,Version,ModuleBase
42+
PS C:\windows\system32> Update-Module -Name ContosoServer -RequiredVersion 1.5
43+
PS C:\windows\system32> Get-Module -ListAvailable -Name ContosoServer | Format-List Name,Version,ModuleBase
4444
Name : ContosoServer
4545
Version : 2.0
46-
ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\2.0
46+
ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\2.0
4747
Name : ContosoServer
4848
Version : 1.5
49-
ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\1.5
49+
ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\1.5
5050
Name : ContosoServer
5151
Version : 1.0
52-
ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\1.0
53-
PS C:\\windows\\system32> Get-InstalledModule
52+
ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\1.0
53+
PS C:\windows\system32> Get-InstalledModule
5454
Version Name Repository Description
5555
------- ---- ---------- -----------
5656
1.0 ContosoServer MSPSGallery ContosoServer module
5757
1.5 ContosoServer MSPSGallery ContosoServer module
5858
2.0 ContosoServer MSPSGallery ContosoServer module
59-
PS C:\\windows\\system32> Update-Module -Name ContosoServer
60-
PS C:\\windows\\system32> Get-Module -ListAvailable -Name ContosoServer | Format-List Name,Version,ModuleBase
59+
PS C:\windows\system32> Update-Module -Name ContosoServer
60+
PS C:\windows\system32> Get-Module -ListAvailable -Name ContosoServer | Format-List Name,Version,ModuleBase
6161
Name : ContosoServer
6262
Version : 2.8.1
63-
ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\2.8.1
63+
ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\2.8.1
6464
Name : ContosoServer
6565
Version : 2.0
66-
ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\2.0
66+
ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\2.0
6767
Name : ContosoServer
6868
Version : 1.5
69-
ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\1.5
69+
ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\1.5
7070
Name : ContosoServer
7171
Version : 1.0
72-
ModuleBase : C:\\Program Files\\WindowsPowerShell\\Modules\\ContosoServer\\1.0
73-
PS C:\\windows\\system32> Get-InstalledModule
72+
ModuleBase : C:\Program Files\WindowsPowerShell\Modules\ContosoServer\1.0
73+
PS C:\windows\system32> Get-InstalledModule
7474
Version Name Repository Description
7575
------- ---- ---------- -----------
7676
1.0 ContosoServer MSPSGallery ContosoServer module
@@ -79,8 +79,36 @@ Version Name Repository Description
7979
2.8.1 ContosoServer MSPSGallery ContosoServer module
8080
```
8181

82+
### Update the module with a prerelease version, requires -AllowPrerelease flag
83+
```powershell
84+
PS C:\windows\system32> Get-InstalledModule
85+
Version Name Repository Description
86+
------- ---- ---------- -----------
87+
1.0 ContosoServer MSPSGallery ContosoServer module
88+
1.5 ContosoServer MSPSGallery ContosoServer module
89+
2.0 ContosoServer MSPSGallery ContosoServer module
90+
2.8.1 ContosoServer MSPSGallery ContosoServer module
91+
92+
PS C:\windows\system32> Find-Module ContosoServer -AllowPrerelease
93+
94+
Version Name Repository Description
95+
------- ---- ---------- -----------
96+
3.0.0-alpha ConstosoServer MSPSGallery The PowerShell Contoso Server deployment tools...
97+
98+
PS C:\windows\system32> Update-Module -Name ContosoServer -AllowPrerelease
99+
PS C:\windows\system32> Get-InstalledModule
100+
Version Name Repository Description
101+
------- ---- ---------- -----------
102+
1.0 ContosoServer MSPSGallery ContosoServer module
103+
1.5 ContosoServer MSPSGallery ContosoServer module
104+
2.0 ContosoServer MSPSGallery ContosoServer module
105+
2.8.1 ContosoServer MSPSGallery ContosoServer module
106+
3.0.0-alpha ContosoServer MSPSGallery ContosoServer module
82107
83-
### Update the TestDepWithNestedRequiredModules1 module with dependencies.
108+
```
109+
110+
111+
### Update the TestDepWithNestedRequiredModules1 module with dependencies.
84112
```powershell
85113
Find-Module -Name TestDepWithNestedRequiredModules1 -Repository LocalRepo -AllVersions
86114
@@ -104,5 +132,8 @@ Version    Name                               
104132
2.5        RequiredModule3                     LocalRepo   RequiredModule3 module
105133
1.0        TestDepWithNestedRequiredModules1   LocalRepo   TestDepWithNestedRequiredModules1 module
106134
2.0        TestDepWithNestedRequiredModules1   LocalRepo   TestDepWithNestedRequiredModules1 module
135+
136+
137+
107138
```
108139

0 commit comments

Comments
 (0)