This repo includes automated Constrained Semantic Versioning (CSemVer) for MSBuild projects
Note
This repository is historically named for only the build tasks but that name is not very very representative of reality anymore. The repo does contain actual build tasks, but also a library for working with CSemVer that includes a number of unit tests to ensure it is operating correctly. Previous releases of only the tasks had some errors on edge cases where it wasn't reporting the correct version for a build. This warranted an update and re-work to support actual testing of the task itself.
Officially, NUGET Packages use a SemVer 2.0 (see http://semver.org). However, SemVer 2.0 doesn't consider or account for publicly available CI builds. SemVer is only concerned with official releases. This makes CI builds producing versioned packages challenging. Fortunately, someone has already defined a solution to using SemVer in a specially constrained way to ensure compatibility, while also allowing for automated CI builds. These new versions are called a Constrained Semantic Version (CSemVer).
A CSemVer is unique for each CI build and always increments while supporting official releases. In the real world there are often cases where there are additional builds that are distinct from official releases and CI builds. Including Local developer builds, builds generated from a Pull Request (a.k.a Automated buddy build). CSemVer doesn't explicitly define any format for these cases. So this library defines a pattern of versioning that is fully compatible with CSemVer and allows for the additional build types in a way that retains precedence having the least surprising consequences. In particular, local build packages have a higher precedence than CI or release versions if all other components of the version match. This ensures that what you are building includes the dependent packages you just built instead of the last one released publicly.
Full documentation on the tasks is available in the project's docs site
Important
There is one significant difference from the behavior in the official CSemVer. Sadly the specs are silent on the issue of a File Version, and the Playground hints that the LSB of the Revision field of a File Version "Quad" indicates a CI build (ODD). ^1^. However, that would lead to FileVersion comparisons where all CI builds are ordered ahead of any release builds of the same version number. This is backwards from the expressed intent. Therefore, the Ubiquity.NET.Versioning libraries and task DO NOT do this. They implement the exact opposite (LSB == RELEASE BUILD). That way any release builds have a sort order that is greater than a CI build of the same version number.
The build uses a common PowerShell module pattern for Ubiquity.NET projects. To build the sources
use the Build-All.ps1 script. You can also open the src/Ubiquity.NET.Versioning.slnx in any
editor/IDE that has support for the slnx solution format. (Visual Studio 2022 is used but other
options may work, though they are not supported. If you have experience with other IDEs, then PRs
are welcome for additional support - but such PRs MUST NOT break the VS support, and you
must be willing to maintain such support going forward.)
Important
It is important to note that IDE builds of a clean repo get will FAIL! This is due to the
mechanisms used to eliminate circular dependencies while still supporting automated versioning
of the projects themselves. To resolve this, you must run the .\New-GeneratedVersionProps.ps1
at least once to create the imported generatedversion.props file. This is also generated by
the Build-All.ps1 script, which is the recommended means of generating the required file. This
is only needed the first time (or any time the buildversion.xml changes).
^1^See: This issue which was reported upon testing this library and found inconsistencies.