DscResources
DscResources copied to clipboard
PowerShell
DSC Resource Kit modules should use Semantic Versioning
DSC resource kit modules should use semantic versioning. There are issues when using non-semantic versioning and newer versions of NuGet.
NuGet will normalize versions to be semver, in DSC case removing the trailing zero (2.3.0.0 to 2.3.0). This will create a mismatch between the psd1 and module version folder causing Import-Module to fail loading the module.
I run into this issue when replicating DSC resource kit modules from PowerShell Gallery to my company's internal Artifactory repository.
Please refer to PowerShell/PowerShellGallery#55 for more information.
Hi @tnieto88, Thanks for the feedback.
I'm keen to use SemVer for many reasons, as long as we keep the NuGet compliant format for pre-releases.
Ideally, in my opinion, we'd use something like gitversion to consistently version our releases.
The problem here is that it's quite a bit of a change on our current release process, so it'll take some time to transition.
We're already looking at ways to make the release process a bit more transparent so that the community can contribute.
Stay tuned! ;)
@gaelcolas My main concern is that DSC resources are using four digit version with a 0 in forth position. NuGet will normalize that version that to a three digit version number causing the module manifest and package version not to match. For more information about NuGet version normalization: https://docs.microsoft.com/en-us/nuget/reference/package-versioning#normalized-version-numbers
To resolve this issue the DSC modules will need to use a three digit versions that will not get normalized. From what I've seen in the last year of releases DSC resources never uses the fourth position so it shouldn't be an issue migrating from four digit to three digit version.
The core issue driving this issue in nuget here: https://github.com/NuGet/Home/issues/3050
Either drop to a 3 part version number or place anything except 0 in the 4th part. This will mitigate a lot of frustration for people trying to use an internal PSRepository.
I reckon we're going to need to get a fix for this sooner rather than later and drop the trailing number if it is a 0 when publishing/deploying as @KevinMarquette says. This will require modifications to the publish scripts that @kwirkykat wrote, but I don't see that is a major problem - should be a simple change. But it will mean the resources drop the last digit in the PS Gallery (because they're always a zero).
@johlju , @gaelcolas - do you see a problem with us doing this before the next release? Would need to run it past Katie I'd think.
I have no issue with changing, but what happens when users run Update-Module? Will it see it as a new version if existing modules are present? Will it see 3.1.0 as higher than 3.0.0.0? 🤔
@johlju PowerShellGet does a version comparison so 3.1.0 is newer than 3.0.0.0.
C:\> [version]'3.1.0' -gt [version]'3.0.0.0'
True
NuGet will normalize versions to be semver, in DSC case removing the trailing zero (2.3.0.0 to 2.3.0).
@tnieto88 - it only removes the trailing zeros and some leading zeros. So you can have a 2.3.0.1, but it will change your 2.03.0 or 2.3.0.0 to 2.3.0.
It would be great if this group does not make the same mistakes that the NuGet team has made in this regard. The intention for version normalization in nuget was to make it easier for nuget.org to sanely deal with package versions on such a massive scale. The mistake was that it should have only been made a requirement and filter for packages published to that repository and others that elect to impose that restriction. It should not have been forced on every non-public nuget repo by changing a value the program is expected to take verbatim.
If you like irony, in the case of NuGet, they are trying to coerce a flavor of SemVer and knowingly introduced a breaking change to do it, but did not update the major version number (which SemVer dictates should happen).
How is the DSC Resource Kit published so that the 4 part version is showing up correctly in PSGallery? The core issue here is that Publish-Module is using NuGet and NuGet is packaging them in a different way.
The modules are released using the version in the module manifest which is using 4-part version. It’s a manual process where most likely Publish-Module is used.
In the first module automatically released in DSC Community https://github.com/dsccommunity/GPRegistryPolicyDsc we switch to using 3-part version number.
I was only asking about publishing because Publish-Module is handing the work off to nuget. The publishing process must be using a down level version of nuget to preserve the 4 part version number for the gallery.
@KevinMarquette Ah, now I understand what you meant. Meaning we could have an issue deploying 4-part in the future if Publish-Module switches to a newer version of nuget? 🤔
More specifically, if the system running Publish-Module updates NuGet then you will also have this issue. Publish-Module doesn't pin to specific version and that is why people are running into this issue. If Publish-Module would handle it, then nobody would have the issue.
All modules transferred to DSC Community can now be converted using the new CI pipeline which uses semantic versioning. Community has already converted some. https://dsccommunity.org/blog/convert-a-module-for-continuous-delivery/