Versioning: SemVer, CalVer and the version of pipeline artifacts

Nordlicht Reisen GmbH, a fictional travel agency, has three kinds of results from its pipelines: the price library as a package, the booking portal as a container and an internal tool as a ZIP file. So far all of them are called "latest", and nobody knows which state is running in production. You are to set a versioning scheme for each result and justify it.

The exam names two skills: versioning of dependencies (SemVer, CalVer) and versioning of pipeline artifacts.

Prior knowledge: K3, lesson 3.7.4 teaches SemVer with the decision of which part goes up, the version from a Git tag with MinVer including enough history in the checkout, dotnet pack, labeling container images with the version of the app and the version under /health. This lesson does not repeat that. It adds what the exam requires on top: CalVer as an alternative, the sorting rules and limits of NuGet, the run numbers of the pipelines as a source of versions and the decision per kind of result. Feeds and views, in which versions become visible, are in lesson 3.1.

SemVer, as NuGet reads it

Microsoft's page "Package versioning" describes a version as Major.Minor.Patch[-Suffix]:

Examples from Microsoft: 1.0.1, 6.11.1231, 4.3.1-rc, 2.2.44-beta.1. Technically, a package author can use any text as the suffix; NuGet treats every such version as a pre-release version and does not interpret it further, leaving the interpretation to the user. Common are -alpha (work in progress, experiments), -beta (feature complete, but with known bugs) and -rc (release candidate, possibly final).

Sorting

According to the SemVer rule, a version without a suffix comes before the pre-release versions of the same number. NuGet orders pre-release versions in reverse alphabetical order and numbers in dot notation numerically. Microsoft's example of sorting by SemVer 2.0 (from the highest version to the lowest):

1.0.1
1.0.1-zzz
1.0.1-rc.10
1.0.1-rc.2
1.0.1-open
1.0.1-beta
1.0.1-alpha2
1.0.1-alpha10
1.0.1-aaa

Note that 1.0.1-alpha10 is below 1.0.1-alpha2, because the sorting is purely alphabetical, while 1.0.1-rc.10 is above 1.0.1-rc.2, because the number is separated by a dot. For numbers without a dot, Microsoft advises leading zeros (beta01, beta05) so that the order is right; that applies only to this scheme. Rule of thumb: Separate the number of the pre-release version with a dot: -rc.2, -rc.10.

What older clients do not understand

NuGet regards a version as specific to SemVer 2.0.0 if the pre-release label is separated by dots (1.0.0-alpha.1) or the version contains build metadata (1.0.0+githash). Such a package on nuget.org is invisible to older clients; only NuGet 4.3.0 or newer, Visual Studio 2017 from version 15.3 and the .NET SDK 2.0.0 or newer (as well as certain third-party programs) see it. When you publish to a feed of your own, check which clients your users have.

Two more rules from the page: nuget.org rejects every package without an exact version number. And when consuming, you can specify an exact version or a range of allowed versions.

Pre-release versions during resolution

NuGet decides by one rule whether it considers pre-release versions: if the project or any package in the graph requires a pre-release version of a package, stable and pre-release versions are included, otherwise only stable ones. When NuGet chooses among different requirements, it takes the lowest version that meets all of them (rule of the lowest applicable version). If that is not possible (for example, A requires exactly 1.0.0 of B and C requires at least 2.0.0), NuGet reports an error; then the topmost application should add a direct dependency on B, because the direct dependency wins. For error NU1103, Microsoft says: if only pre-release versions exist but a stable version is required, adjust the version range so that pre-release versions are allowed. And for floating versions with central package management, Microsoft advises fixed versions; otherwise the setting CentralPackageFloatingVersionsEnabled is needed (error NU1011).