RFC0004-PowerShell-Module-Versioning

joeyaiello commented 8 years ago

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 commented 8 years ago

Thank you for fixing the versioning. This looks great

glennsarti commented 8 years ago

:+1:

rkeithhill commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

@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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

@smurawski Good point, thanks!

powercode commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

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 https://github.com/PowerShell/PowerShell-RFC/issues/10#issuecomment-215254323

https://powershellstation.com

rkeithhill commented 8 years ago

@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 commented 8 years ago

I was replying to @michaeltlombardi. :-)

rkeithhill commented 8 years ago

@MikeShepard Ah, missed that. Sorry.

michaeltlombardi commented 8 years ago

@rkeithhill: Okay, I think I understand now. We were looking at two different problem sets:

Generally Pre-Release Modules

Per SemVer, modules without a stable API (still changing/removing functions, non-fixed DSL, etc) would be versioned 0.Y.Z

Released Modules

Once a generally pre-release module has stabilized and is ready for first production release, it would bump to 1.Y.Z and increment Y and Z as necessary. The next time a change is made which breaks backward compatibility, 1 will increment to 2.

Pre-Release Versions of Current Updates

The above doesn't address the problem of people wanting to beta-test version 2.Y.Z of a module before the author/maintainer marks it as fit for production. Essentially, we're discussing adding a "not-fully-ready-yet" flag to modules when we're past 0.Y.Z but we want to make the current work-in-progress version available?

If that's the case, following strict semantic versioning and adding the PreRelease flag definitely makes the most sense.

Figuring out how to make it play nice with .NET versions and catch the second and third order effects sounds trickier.

Edit: Clarity, grammar.

rkeithhill commented 8 years ago

@michaeltlombardi

Essentially, we're discussing adding a "not-fully-ready-yet" flag to modules when we're past 0.Y.Z but we want to make the current work-in-progress version available?

Yup. As soon as you try to handle prerelease versions of a module with a convention like 0.Y.Z then it breaks down for prereleases of versions 1.1.0, 1.2.0, 2.0.0, etc.

One really, really cheesy convention that could handle future prereleases would be to make the range Major.Minor.Patch.0 - Major.Minor.Patch.999 be recognized as prerelease. Production would require -ge Major.Minor.Patch.1000.

OK now that I said that, I think I just threw up a little in mouth. Blech! Besides, that doesn't work with existing modules which have versions like 1.0.0.0. They would be flagged incorrectly as prerelease.

BladeFireLight commented 8 years ago

I don't like any of the alternates

Pre-release of 2.0 should stay on GitHub, and after 1.0 only stable should be in the gallery.

smurawski commented 8 years ago

@bladefirelight The problem with that is it is harder to get folks to test. When you have it integrated into the package management process (with explicit intentions to get prerelease versions) you make it easier for people to try out newer version. Also, for people who want a particular bug fix that may not get shipped a real release for a while, pre-release packages can be a big helper.

I've seen projects where we had to depend on pre-release versions of components because it was taking too long to get the actual release shipped and the fixes in the pre-release were critical.

BladeFireLight commented 8 years ago

I see your point, but if you willing to go beta in production (for good reason) then you should be competent enough to package a module from github.

It would be nice to have a flag for non-release. however the gallery does not support backwards numbering. so you cant patch a security release for 1.5.6 when you have published 1.9.99-beta5 with the same module name.

dlwyatt commented 8 years ago

That's a good point. We should be able to publish any version number we like. Separate issue, I suppose, but still related.

rkeithhill commented 8 years ago

@BladeFireLight

so you cant patch a security release for 1.5.6 when you have published 1.9.99-beta5 with the same module name.

Well that would be an issue the PSGallery would need to fix, if that's the case. Regardless of this "prerelease" issue you should be able to publish a patch to a previous version - say 1.5.7 when the latest is say 2.0.0? Just because there is a newer version, doesn't mean everybody can adopt it. Perhaps 1.5.7 supports PS 3 and 2.0.0 only supports PS 5.

powercode commented 8 years ago

The PSGallery has in private communication said they will change that. No timeframe though.

smurawski commented 8 years ago

@bladefirelight It's not about competence, it's easy of adoption and discovery. I'll never go look for pre-release versions if I have to track down each github repo and look at tags or releases, but find-module -prerelease with some search criteria is much easier.

BladeFireLight commented 8 years ago

so long as older versions of find-module are going to default to -prerelease:$false from the server's perspective, I'm fine with that approach.

gaelcolas commented 8 years ago

I concur with @rkeithhill and @smurawski that priority should be given to adoption and discovery, using the semver+pre-release flags/search capabilities: you want consumer feedback early, this needs easy and centralized discovery/update. It's easier to search and try new modules from gallery, rather than trying to use github as a _pre-release gallery _to discover and install modules. Github's amazing for collaboration, source sharing and so on, not so much as a PowerShell Gallery ;) @BladeFireLight has a good point with re-releasing any version you'd like to patch older version though! Can we get rid of the 'x' now?

matthitchcock commented 8 years ago

I definitely support using semver, kill the 'x' and 'c' and so on.

HemantMahawar commented 8 years ago

I think there is consensus developing on the versioning approach ... great. But there is one aspect that the RFC or any of the comments don't talk about - the impact of dropping 'x' from the module name.

Consider xActiveDirectory module. In the 'drop the x' approach, it would become ActiveDirectory and on systems where these resources will be used, ActiveDirectory role will be turned on and there will be 2 version of this module:

One in System32 - owned by Active Directory team with AD cmdlets
Second in ProgramFiles - containing only DSC resources

I feel as part of this RFC (or maybe another RFC), we should also close on potential names for modules in 'drop the x' approach/world.

BrianFarnhill commented 8 years ago

@HemantMahawar Since this RFC is called "Module Naming and Versioning for PowerShell Gallery" I think this is the RFC for that discussion as opposed to another RFC.

In terms of simply removing the "x" I believe just naming the module to something that shares the same name will cause issues. For example, if I'm using xHyper-V and we rename it to "Hyper-V" we then have two different versions on the server - any other scripts I've written that use Import-Module Hyper-V will then have an ambiguous reference to a module name there.

There is also consideration to be given to the implied intent of the module based on its name as well. Take your example there - if both modules are called ActiveDirectory then it is unclear what each would do, and it wouldn't be unreasonable to expect that they are both the same in terms of functionality, but really one is to manage the product directly, and one to manage the DSC resources.

Based on that, I would propose that when we remove the "x" we look at a naming format that clearly identifies the modules as having DSC resources in them. For example, "xSharePoint" could become "SharePointDSC" as that clearly identifies that this is the module for DSC resources for SharePoint. There is an argument here that putting "DSC" in to the name means that you become limited to really just shipping DSC resources in the module, and not other scripts or components - I'm not aware of any other DSC resource modules currently that do this (that being said I've not used them all directly at this point either) but I would suggest that components that aren't related to the DSC resources can/should be delivered in a separate module anyway. I would be keen to know if anyone has a specific use case for this scenario though so we can apply the thinking to that.

matthitchcock commented 8 years ago

I'm generally not a fan of naming conventions. I spent many years in a big enterprise arguing with people who didn't use naming conventions correctly. It was a pointless waste of energy and I learned in the end that attributes and values, or metadata, were far better for identification of what resources were and what they did rather than names themselves. You can never enforce a naming convention and everyone has their own interpretation of it. While a Name is needed for everything, it is more for human readability and for us to interpret than anything else. Perhaps instead of focusing on and relying on naming we need to consider making it easier to add and display other information such as GUIDS and Tags. I haven't thought through how this would be implemented yet, but I think using "Import-DSCResource -ModuleGUID 'some guid' is probably more reliable than hoping someone hasn't overwritten the AD module or created a duplicate.

pcgeek86 commented 8 years ago

I spent many years in a big enterprise arguing with people who didn't use naming conventions correctly. It was a pointless waste of energy and I learned in the end that attributes and values, or metadata, were far better for identification of what resources were and what they did rather than names themselves.

NICELY said, Matthew. 😄

smurawski commented 8 years ago

@matthitchcock "in an enterprise" naming and "publicly available project" naming are two different things. Naming is all about discovery. There are orgs that will not use 'x' resources since the only references to the 'x' prefixing is about experimental. Also, as the gallery stands, I can ship an ActiveDirectory or WebAdministration module. This can potential cause conflict with internal modules - and there should be some either placeholders or something in place to prevent someone from squatting on already taken names in the core of shipping PowerShell.

@HemantMahawar in regards to name conflicts, making xActiveDirectory into ActiveDirectory.DSC or something like that would disambiguate from existing modules. (as also suggested by @brianfarnhill)

kilasuit commented 8 years ago

I agree with @BrianFarnhill on the naming of the modules to be _DSC so SharePoint_DSC etc (dot, underscore, dash etc - as long as its clear its suffixed with DSC)

One thing that I think would be beneficial would be to essentially have 2 PSGallerys - the one we currently have and a second at beta.powershellgallery.com (a suggestion) and my reasoning for this I believe would negate the prerelease issue if the Publish, Find, Save & Install Module functions would implement a check for a Prerelease switch and only pull from / push to the beta gallery. This would in my opinion be the simplest path to go down from a technical perspective however I'm happy to be corrected on this.

This allows customers to choose to be able to search for prereleased versions or not & allow module authors a test ground to publish to as well, which I think would help adoption further whilst helping to alleviate the concerns that @BladeFireLight & @powercode have raised although not in their entirety but it would allow you to release modules in different states to both galleries including bugfixing of previous released versions after a new major version is released. Though this really is a workaround not a resolution for that issue.

Also, as the gallery stands, I can ship an ActiveDirectory or WebAdministration module. This can potential cause conflict with internal modules - and there should be some either placeholders or something in place to prevent someone from squatting on already taken names in the core of shipping PowerShell.

Agreed and there is something that could be easily done to stop that - release a blank module for each of the modules shipped as parts of the Microsoft product lines by the product teams to the gallery and then mark it as hidden on the gallery. This would then allow teams to eventually OS their modules ( thinking aloud here - SQLPS - which has a lot of votes to be open sourced right now see https://connect.microsoft.com/SQLServer/feedback/details/2442788/open-source-sqlps-and-publish-code-on-github )

Also one of the core items that @matthitchcock raised is the additonal Metadata that we have in the Gallery and it would be useful to have additional parameters available to us via Find-Module like Author, CompanyName etc to allow people to do this

Find-Module -CompanyName "PowerShellTeam"

instead of

Find-Module * | Where-Object {$_.CompanyName -eq "PowerShellTeam"}

Though that example is probably better pushed to User Voice as an improvement to the PowerShellGet Modules than for really discussing here but again would help to raise awareness of how to find Microsoft published modules easier.

PS thanks @KarolKaczmarek for reminding me of this thread :-)

splatteredbits commented 8 years ago

Semantic versioning can't be implemented today in PowerShell or the PowerShell Gallery. I would prefer to see it implemented properly than have a workaround in place that has to stick around forever because temporary solutions almost always turn into permanent solutions.

If possible, I'd like to see the PowerShell Gallery function exactly like nuget.org: have pre-release flags and use semantic versions (separate things!) that aren't tied to .NET's Version class. .NET doesn't have native support for semantic versions, yet nuget.org does and uses them.

What's the downside to waiting for a full implementation? Teams can't release betas of versions after 1.0.0. I can live with that. (In fact, I did. Version 2 of my Carbon module was in development for six months, with a few alpha versions. Those alphas were only available via the project's Bitbucket download page.)

So, I vote for waiting for native support for semantic versioning.

DCtheGeek commented 8 years ago

For the naming of modules, there are a few choices that folks have listed and each has pros and cons in my book. Here are my quick thoughts using xSharePoint as an example:

Simple Suffix - SharePointDSC - I don't like this for the simple reason that it won't be easy to search for. If someone names a module 'PODSc' or something similar, then a search for anything that ends in 'DSC' will be inaccurate.

Dash Suffix - SharePoint-DSC - I also don't like this one because instead of looking like a module, it now looks like a cmdlet. While the dash makes it easily searchable and solves the Simple Suffix issue, it could still lead to confusion.

Period Suffix - SharePoint.DSC - This is a little bit closer, but the issue I have here comes from being a C# or Java developer or anything that uses dot notation for classes and attributes. This, to me, makes it look like 'DSC' is a subclass of class 'SharePoint' or an attribute of it. Either way, could lead to confusion.

Underscore Suffix - SharePoint_DSC - This is actually my preferred choice because of the previously listed detractors. I know some folks use the underscore to mean specific things, but I think it's the best of the available options.

BrianFarnhill commented 8 years ago

@DCtheGeek i agree with most of what you have there. I would lean more towards the dot though, because in the context of where we refer to module names we aren't usually anywhere near somewhere that we would be referring to properties or attributes (Import-Module and Import-DscResource being the two big ones I imagine), and the dot also lines us up with other modules that we have published already (I'm thinking of the Azure cmdlets where they are all "Azure.[resource type]" for the module names).

That said - at the end of the day I'm not going to lose any sleep over the specifics of the suffix, as long as there is one and we make it standard I'm good.

ghost commented 8 years ago

@DCtheGeek & @BrianFarnhill & @HemantMahawar et. al regarding renaming from x & conflicts - this spurred lots of talk in the PowerShell team. Consensus inside PS team is that the right thing to do is stick to current PowerShell naming guidelines, & not invent something new for this situation unless needed. The PowerShell naming guidelines are

Use Pascal casing for how to identify names of things. The Networking modules in Windows are good examples (try gmo -li net*).
Names should have the major concept in front, followed by subsequently minor concepts, so that all modules pertaining to the same types of things show up together. Same example, note NetSwitchTeam or NetworkSwitchManager specifically.
.Net says to handle acronyms in Pascal casing by either not using them, or keeping them in caps for 2 letters & doing Pascal casing for 3 letters or more. PowerShellDsc would be a good example here.

As far as separators, again there wasn't a need to invent something new. So that you know, I went into this with a personal preference of having a separator, to help with locating things, but we already have mechanisms to do that. Find-Module -includes dscresource, lists the items with DSC resources in them (that's how we do it from the gallery).

ghost commented 8 years ago

@rkeithhill & @BladeFireLight @smurawski et. al, around handling preview numbering after a 1.0 version has been released. Responses appreciated as to whether or not this is sufficient to meet the needs. If it is, I'll update the RFC accordingly.

As noted, PowerShell today cannot support the full SemVer approach of Major.Minor.Bug-Preview, since our version checking is based off .Net. Going to full SemVer support is unfortunately a major & risky change, so we'll have to do it at the right time in the dev cycle.

Based on the feedback, none of the suggested alternatives really work well, so until we can support SemVer fully, what we are proposing is the following:

We will generally recommend keeping previews in GitHub, but @smurawski is right, that's insufficient and we need a reasonable story for the gallery.
For preview modules going into the Gallery, you need to keep the module names & package names & resource names unchanged or code written against them won't work.
We can build in reliance on a tag of "Preview", if that gets consensus. This is just a tag, but we can use it to do filtering in the Gallery so that users by default will not get Preview items. It can be easily specified today using -Tag Preview, which would return the results (or by specific version). This allows the majority of users to get the latest update as production quality, unless they specify they are OK with preview.
We have an open work item to allow publishing with a new unique version number that's lower than the current highest version number, if user specifies -Force. That will solve the ability to publish an update to 1.6.3 as version 1.6.4, after a version 2.0.0 is released. Requirement is that it is unique, & guideline is that it must be bigger than the previous production version.

What this means is that the guidelines for module versioning would state that the preview release of MyGreatModule version 2.0.0 that's released after the production 1.5.0 version would be released as MyGreatModule version 2.0.0, & contain a tag of "Preview". It would not show up by default in Find-Module, but it would if I specified Find-Module -name MyGreatModule -Tag Preview

smurawski commented 8 years ago

@JKeithB I don't underestimate and can appreciate the risk of changing module versioning to semver.

I caution against any route other than path 1 and moving to support semver in PowerShell. That's a major bit of technical debt that will have to be eaten at some time.

Preview tags and back versioning modules can lead to a very confusing end state. I would save the dev time on those efforts and put them towards semver support in the module manifest.

By moving to a tag for "Preview", you now have made the effective module version the System.Version version plus the tag and if I need to confirm whether a module that was deployed was Preview or not, I need to check two things (one of which isn't directly surfaced in the output of Get-module for example). And if you wanted to add that preview support throughout PowerShell, any command that reports a module version would need to know how to look for that particular tag. Another problem - looking at a DSC configuration with import-dscresource - there would be no way from just looking at the configuration and import-dscresource statement as to whether it was using preview functionality (e.g - I'm doing code review in github - do I need to also pull each module or query each one to validate it isn't preview?) If it is in the module version right up front, all this stuff is in your face.

ghost commented 8 years ago

@smurawski - can't really speak to when we'll be supporting Semver, but you are correct in saying that it is a significant change. Two things I did not identify in the requirements for the proposal made above 1> We wanted guidelines that could be used today that can be made to work in downlevel systems without breaking changes, 2> We wanted to ensure users who currently rely on Find-Module/Install-Module to be able to continue to acquire the latest version from the gallery without making them think about whether or not it was preview. So, waiting on full SemVer support with these guidelines doesn't meet all the requirements. We did consider adding this to the module manifest as a separate field, but it has some negative impacts. Will reconsider that rather than tags, & respond.

smurawski commented 8 years ago

@JKeithB "Making it work today" sets a the pattern and removes some of the impetus for making the breaking change. It could be seen as "good enough" and left there.

You are making a special case of behavior that is different from other nuget-backed packaging systems (like nuget for .Net or Chocolatey).

Once you put a workaround in place and if you do eventually go semver, you'll have to deal with an ecosystem full modules which could contain two different ways of being "preview" or "prerelease" and every tool that needs to know about module versions will need to deal with both ways of specifying versions.

You are adding future problems and not removing the obstacle of "Semver is not System.Version".

splatteredbits commented 8 years ago

I recommend using the revision number (the fourth/last) of the version to denote that something is in preview. If the revision number is greater than -1 (the value for not set/empty), then the gallery and convention dictates that it is a preview version. Support for this would have to be built into the gallery so that preview versions are not downloaded, installed, and/or updated to without explicitly asking for it. While version 2.0.0 of my module was in alpha, a lot changed and I broke compatability with previous alphas at least once. I actually had someone request different version numbers for each alpha release, as having the same version didn't work for them. So, I started using the revision number. In my release notes and descriptions, I used a semanatic version, e.g. 2.0.0-alpha.34, but the actual version of the module and assemblies was 2.0.0.34.

Someday, semantic versioning may be part of the PowerShell Gallery. But will it ever be part of .NET and/or core PowerShell? I hope so, but in PowerShell 5 modules are stored in version-specific directories, e.g.

Carbon
+ 2.0.0.35
+ 2.0.0

Even if the gallery supports semantic versioning, unless PowerShell supports it, nobody will be able to install side-by-side preview versions. So using the "revision to denote preview status" may have to continue and/or be required until semantic versioning comes to PowerShell.

KirkMunro commented 8 years ago

@smurawski: What does having some support for Preview today, via a tag or whatever, take away from having full support for SemVer later? The preview problem exists now. I don't think the solution is either/or, and it seems from your responses that there is some fear that SemVer wouldn't happen if there was another solution in place that partially solved the problem today. Yet nobody said that having something in place now would stop them from doing SemVer later (from what I have seen anyway). Pushing for SemVer later is absolutely the right thing to do, but putting a solution in place now that supports identification of Preview versions of modules in current versions of PowerShell is also the right thing to do IMHO.

As for tooling supporting one way to identify preview now and another later, that's part of tooling work. Things change. PowerShell syntax changes. And tools update as the language matures. There's nothing to be afraid of when it comes to tooling updates to support one preview mechanism vs another. I don't understand the fear of "all that work" when it doesn't seem like there would be so much work involved, from my perspective anyway.

Jaykul commented 8 years ago

I think assuming that the build number means "pre-release" would be unnecessarily restrictive.

The right answer seems to me to be to just do the same thing NuGet does for Visual Studio assembly dependencies: SemVer is supported by the repository, and the packages, and the installer is "prerelease" aware, but developers still have to separately version their actual products (the dlls) using System.Version...

Assuming developers use distinct version numbers for the actual module for each build (regardless of how they increment them -- my teams typically just increment the revision number of an assembly to 10000 or so when we start pre-release for the next release, but that's just a detail), you can still do side-by-side installs, and the gallery and PowerShellGet are the only ones that need to use SemVer...

mattheyan commented 8 years ago

I agree with @Jaykul. It seems that a pre-release designation isn't something that an installed PS module should be concerned with. It is a concern of the package manager and repository.

Consider this example workflow: Module A is at version 1.0.0. I pre-release 1.1.0-xyz with some minor changes. Everything checks out, so I'm ready to release. But this is the same module, just cleared for release. So, shouldn't I be able to release 1.1.0 without a pre-release designation? And, whether you had previously installed the pre-release or install after release, it's still the same module. Conversely, if I have to make some changes, I should publish another pre-release - 1.1.1-xyz - and continue the process. Or, if I'm extremely confident in the fixes go straight to release. It's up to the dev/team, the point is that the package manager supports the pre-release -> release flow and its up to you to implement it however it makes sense. From my perspective, the package version and module version are separate (though closely related) pieces of information with slightly different purposes.

I would love to see PsGet and the gallery align with other NuGet-based package managers and support semver and pre-releases irrespective of any potential changes to PowerShell itself.

Also, in terms of the naming convention of modules, I agree with others who have said that a naming convention (if used at all) should help reveal the content of the module. It should be the job of the package version to indicate where the module is in terms of stability, completeness, etc. I'd love to see the 'x' convention phased out in favor of pre-release flags, or probably in these cases a 0.* version to indicate that the module is still experimental and may not be ready for prime-time.

TravisEz13 commented 7 years ago

@joeyaiello The spec says there will be 4 segments and semver/nuget have 3 segments. This difference will make things difficult when packaging PowerShell into NuGet (PowerShell Gallery).

ghost commented 7 years ago

@TravisEz13 The spec says there MAY be a 4th segment, it will be supported by the Gallery as this RFC started for the Gallery/PowerShellGet, and it is needed to support Microsoft build systems that insist on the 4th segment for the build number.

TravisEz13 commented 7 years ago

@JKeithB I disagree that a 4th segment is needed to support the Microsoft build system. DotNet has seemed to have an implementation ends up with 3 numeric segments in their NuGet packages, despite having 4 segments in the build of the actual binary. Perhaps we should look into how they have implemented their packaging. Here is a screenshot of System.Reflection.Metadata with the package and assembly version highlighted:

ghost commented 7 years ago

@TravisEz13 You may choose to disagree but there are groups inside MSFT who have given us the requirement to support it. Happy to have discussion on specifics, but the requirement is valid. Look at the build numbers for Windows.

SphenicPaul commented 6 years ago

Personally, I like the flexibility of using 3 and 4 segment versions AND the option of using the suffix strings.

Whilst I appreciate that this thread may be specific to the PowerShell Gallery, I'd like PowerShell modules in general to support all the above options (i.e "Alternative 2"). In particular, where users/devs/organisations have their own private repositories (file shares or utilising NuGet repositories), I believe they should have the flexibility of maintaining their own conventions - many may already have their own standards for private NuGet repositories and being able to adopt similar standards for PowerShell modules would make sense (to me atleast).

If "Alternative 2" is chosen/used/implemented, whilst the PowerShell Gallery may have it's own rules/restrictions on the suffix/strings that can be used, I don't feel these limitations should apply to PowerShell versioning as a whole. Organisations may use particular conventions (e.g. branch names, dates/times etc.) as parts of these suffixes and I feel that being able to publish modules to private repositories without those restrictions would be useful (required even).

It would be good for the PowerShell Gallery to adopt a sound/flexible approach to PowerShell module/script/DSC versioning that could be adopted/accepted as a standard more widely.

Cheers,

Paul

PowerShell / PowerShell-RFC