-
Notifications
You must be signed in to change notification settings - Fork 123
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
RFC0004-PowerShell-Module-Versioning #10
Comments
Thank you for fixing the versioning. This looks great |
👍 |
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
I would stick with recommendations of |
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.) |
@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.
For git repos Perhaps, including |
Another possible way to deal with the preview versioning (for now) is that the 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 |
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 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. |
@smurawski Good point, thanks! |
How about a separate field that only indicates eventual prerelease status? |
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. |
Doesn't semver already cover beta vs production-ready versioning?
Does .NET versioning preclude 0.Y.Z versions, or is the problem that it would require re-versioning for many existing pre-release modules? |
What about pre-release versions of non 1.0 software? Like a pre-release of On Wed, Apr 27, 2016 at 5:46 PM, Michael T Lombardi <
|
@michaeltlombardi Semver does cover 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 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 @MikeShepard That would simply be |
I was replying to @michaeltlombardi. :-) |
@MikeShepard Ah, missed that. Sorry. |
@rkeithhill: Okay, I think I understand now. We were looking at two different problem sets: Generally Pre-Release ModulesPer SemVer, modules without a stable API (still changing/removing functions, non-fixed DSL, etc) would be versioned Released ModulesOnce a generally pre-release module has stabilized and is ready for first production release, it would bump to Pre-Release Versions of Current UpdatesThe above doesn't address the problem of people wanting to beta-test version If that's the case, following strict semantic versioning and adding the Figuring out how to make it play nice with .NET versions and catch the second and third order effects sounds trickier. Edit: Clarity, grammar. |
Yup. As soon as you try to handle One really, really cheesy convention that could handle future prereleases would be to make the range 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 |
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. |
@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. |
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. |
That's a good point. We should be able to publish any version number we like. Separate issue, I suppose, but still related. |
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 |
The PSGallery has in private communication said they will change that. |
@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. |
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. |
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 ;) |
I definitely support using semver, kill the 'x' and 'c' and so on. |
I think there is consensus developing on the versioning approach ... great. 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:
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. |
@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. |
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. |
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. |
@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. |
@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.
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). |
@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:
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 |
@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. |
@smurawski - can't really speak to when we'll be supporting Semver, but you are correct in saying that it is a significant change. |
@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". |
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.
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. |
@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. |
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... |
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. |
@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). |
@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 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. |
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 |
Since @SphenicPaul woke this thread up, it's worth saying: In PowerShell 6 we have |
@PowerShell/powershell-committee has been working to drive down our RFC debt. Here are the notes that resulted out a meeting on this one:
|
@PowerShell/powershell-committee agrees that the above is accurate |
The specification here matches our recommendations for PowerShell Module Versioning in the PowerShell Documentation |
@SydneyhSmith Ideally, we'd like the merged PR for this to be as up-to-date as the docs you listed. Would you mind making those changes? Thanks! |
Use this issue to comment on this RFC: https://github.com/PowerShell/PowerShell-Language-RFC/blob/master/1-Draft/RFC0004-PowerShell-Module-Versioning.md
The text was updated successfully, but these errors were encountered: