Skip to content

Commit 983572c

Browse files
authored
Update RFC0004-PowerShell-Module-Versioning.md (#163)
Updates this RFC to exactly match the implemented publishing guidelines found at https://docs.microsoft.com/en-us/powershell/gallery/concepts/publishing-guidelines#follow-semver-guidelines-for-versioning
1 parent 4f6c903 commit 983572c

File tree

1 file changed

+14
-7
lines changed

1 file changed

+14
-7
lines changed

5-Final/RFC0004-PowerShell-Module-Versioning.md

+14-7
Original file line numberDiff line numberDiff line change
@@ -32,13 +32,20 @@ This RFC proposes the following guideline for the naming and versioning of modul
3232

3333
* Modules, scripts, commands, and DSC resources should be named as they are expected to be used, regardless of the state (experimental, preview, production, etc.)
3434
* Modules, scripts, commands, and DSC resources should be versioned in a way that aligns with Semantic Versioning, meaning:
35-
* Versions contain at least 3 segments separated by periods: Major.Minor.Patch
36-
* Major version number changes if changes are made that are incompatible with the previous version
37-
* Minor version number changes if functionality is added in a backwards-compatible manner
38-
* Patch version number changes when there is an update that is backwards-compatible and does not add new features
39-
* If a 4th segment is used, it indicates a build number only, with no changes in the component. *Note that this is an open issue*
40-
* Major version 0 (0.x.y) indicates code that is experimental. Version 1.0.0 is expected to be a production-ready version of the code.
41-
* Preview versions of major updates released after the module reaches production-ready state: If the developer desires to publish a preview or experimental copy of a major update, they should do so via a project development site such as GitHub. *Note that this is an open issue.*
35+
* The version should be structured as 3 numeric blocks separated by periods, as in 0.1.1 or 4.11.192
36+
Versions starting with "0" indicate that the package is not yet production ready, and the first number should only begin
37+
with "0" if that is the only number used
38+
* Changes in the first number (1.9.9999 to 2.0.0) indicate major and breaking changes between the versions
39+
* Changes to the second number (1.1 to 1.2) indicate feature-level changes, such as adding new cmdlets to a module
40+
* Changes to the third number indicate non-breaking changes, such as new parameters, updated samples, or new tests
41+
* When listing versions, PowerShell will sort the versions as strings, so 1.01.0 will be treated as greater than 1.001.0
42+
* PowerShell was created before SemVer was published, so it provides support for most but not all elements of SemVer, specifically:
43+
* It does not support prerelease strings in version numbers. This is useful when a publisher wishes to deliver a preview
44+
release of a new major version after providing a version 1.0.0. This will be supported in a future release of the PowerShell Gallery
45+
and PowerShellGet cmdlets.
46+
* PowerShell and the PowerShell Gallery allow version strings with 1, 2, and 4 segments. Many early modules did not follow the
47+
guidelines, and product releases from Microsoft include build information as a 4th block of numbers (for example 5.1.14393.1066). From
48+
a versioning standpoint, these differences are ignored.
4249
* This guideline affects publishing PowerShell modules, commands, scripts, and DSC resources via the [PowerShell Gallery](https://powershellgallery.com), and should not be implied as having broader applicability.
4350

4451
### Alternate Proposals and Considerations

0 commit comments

Comments
 (0)