RFC0004-PowerShell-Module-Versioning

[joeyaiello]

Use this issue to comment on this RFC: https://github.com/PowerShell/PowerShell-Language-RFC/blob/master/1-Draft/RFC0004-PowerShell-Module-Versioning.md

[pcgeek86]

Thank you for fixing the versioning. This looks great

[glennsarti]

👍

[rkeithhill]

First, I like the direction this is going. Semver is really nice for module/pkg level versioning.

RE Alternative 2 and the use of pre-release versioning suffixes, .NET "versions" are required just for strong named assemblies. This is true for NuGet .NET pkgs that contain strong named .NET assemblies as well. However NuGet allows the pkg version to be specified as a string in the nuspec file.

The only issue I see with PowerShell is that internally PowerShell must convert the ModuleVersion field of the manifest to a .NET Version. So what if you added a new field to the manifest such as ModuleSemVersion or some such thing? It wouldn't be the first time a field was added to the manifest (looking at you RootModule).

You would have to deal with the existing .NET versions vis-a-vie this new semantic version but that doesn't seem like it would be too hard. Modules that have published pkgs using .NET versions (say 1.0.0.0) would be required to be greater than their predecessors (1.0.1) when publishing an update using semver.

BTW watch out for using a prelease string like preview. The prerelease field is treated lexigraphically for determing which version is greater e.g.:

1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0

I would stick with recommendations of alpha, beta, rc to ensure proper update version checking.

[dlwyatt]

Yep, something in the PSData table could work to allow the semver pre-release stuff. If present, it overrides ModuleVersion when running Publish-Module. (Would probably be best to combine that with a 4-part version including build number in the ModuleVersion key, as a best practice, so different prereleases still have a unique ModuleVersion.)

[vors]

@dlwyatt I like being able to easily track what version of the module I use, all the way to the source code (not just release notes).

I experimented with including build number in a module version in https://github.com/PowerShell/platyPS After few releases, I tend to remove build number from the version.

• Import-Module for particular version becomes harder. You need exact version, because wild-cards are not supported. So you need to query Get-Module -ListAvailable to see all versions before import (nobody is going to remember the build number).
• Build numbers are somewhat arbitrary and are artifacts of the CI system, not the code itself.

For git repos git describe generates version purely from the source (and source history). That way is not tighted to a particular CI server and generates same version identifiers, when build on another machine uses the same commit. But it includes part of sha1 in a form of string.

Perhaps, including git describe output in a manifest in some field can be used for unique identifiers. And version can remain semver.

[daviwil]

Another possible way to deal with the preview versioning (for now) is that the -alpha is only used as a Gallery module version. Once the module is installed on the system, Import-Module, etc will use the numbered version without the preview suffix. Only the PowerShellGet module would use that information to ensure that the user doesn't install a preview module if they don't want one.

To add to @rkeithhill's point about having a separate module version field that includes the preview suffix, the .NET ecosystem solved this problem by using the AssemblyInformationalVersion for the full semantic version string. Some discussion on the 3 different version attributes for .NET assemblies here:

http://stackoverflow.com/questions/64602/what-are-differences-between-assemblyversion-assemblyfileversion-and-assemblyin

[smurawski]

Love that this is getting some traction. We can't get away from the "x" modules/resources fast enough.

I am in favor of alternative 2 - with @rkeithhill's caution about alpha, beta, rc vs preview.

I would also suggest that the *-package and PowershellGet cmdlets support a -prelease switch so that without that, results with prerelease versions are not accidentally installed. (Makes it intentional.)

The other caution as we move to more versions of modules available is that currently, module dependencies are either "latest" or a specific version. We should be able to specify a range of support, like everything less than major version two, or any minor version greater than 4 of the same major version. This capability makes it easier to allow for dependencies to rev without every contingent module needing to update.

@daviwil I'm not in favor of two different versions floating around - if I get different results from get-module as to what module is installed vs. what find-module/install-module use, that'll make supporting resources much more difficult - "Oh, you have THAT version number, I need the other one." Also, people have a hard enough time revving one version properly, much less two separate ones.

[daviwil]

@smurawski Good point, thanks!

[powercode]

How about a separate field that only indicates eventual prerelease status?
I.E. Only one version field, but a separated one for alfa, beta etc.

[smurawski]

Not a bad idea @powercode, but nuget already supports the prerelease field in versioning, so I say keep it simple and update the one thing.

[michaeltlombardi]

Doesn't semver already cover beta vs production-ready versioning?

0.Y.Z indicating pre-release and X.Y.Z (where X -ge 1) is production-ready.

Does .NET versioning preclude 0.Y.Z versions, or is the problem that it would require re-versioning for many existing pre-release modules?

[MikeShepard]

What about pre-release versions of non 1.0 software? Like a pre-release of
the 2.0 version.

On Wed, Apr 27, 2016 at 5:46 PM, Michael T Lombardi <
notifications@github.com> wrote:

Doesn't semver already cover beta vs production-ready versioning?

0.Y.Z indicating pre-release and X.Y.Z (where X -ge 1) is
production-ready.

Does .NET versioning preclude 0.Y.Z versions, or is the problem that it
would require re-versioning for many existing pre-release modules?

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub
#10 (comment)

https://powershellstation.com

[rkeithhill]

@michaeltlombardi Semver does cover pre-release vs production via the appended -<prelease-name> e.g. 1.0.0-alpha1. The .NET System.Version type precludes this because the last field (Revision) must be an integer. The basic issue is that modules use System.Version and that type has no accommodation for specifying that a release is a pre-release.

This is important for pkg management systems where you want to allow folks who want to install a "pre-release" to do so but they have to explicitly indicate they know they're getting a pre-release. As @smurawski says, there should be a -Prerelease switch on Find-Module, Install-Module, Get-InstalledModule, etc which would be required to even find/install/list prerelease modules. BTW this switch does exists on the Install-Package command for the NuGet Pkg Mgr console in Visual Studio. So perhaps there would be some transfer of learning for devs at least. :-)

Right now there is no concept of "segregating" prerelease modules from production modules on PSGallery AFAIK. This could be solved by adding another metadata field to the ModuleManifest but NuGet has solved this issue using semver. For that matter, PowerShellGet uses NuGet under the covers. Kind of makes sense to just roll with semver - if possible.

I was thinking before this would only impact the ModuleVersion in the manifest but there's more. There's the #Requires -Modules PSWorkflow, @{ModuleName="PSScheduledJob";ModuleVersion=1.0.0.0} which is a .NET Version (I believe) and the Import-Module -RequiredVersion/MinimumVersion parameters are of type Version. :-( Curiously MaximumVersion is of type string. So this makes it harder to use semver in the ModuleVersion. Although changing from Version to string (or a new SemVersion type) might work. It is sort of a "widening conversion" except for that fourth (Revision) field. Argh... Nothing's ever easy. :-(

@MikeShepard That would simply be 2.0.0-alpha1, 2.0.0-alpha2, 2.0.0-beta1, 2.0.0-rc1, etc.

[MikeShepard]

I was replying to @michaeltlombardi. :-)

[rkeithhill]

@MikeShepard Ah, missed that. Sorry.