Skip to content

smaillet/CSemVer.GitBuild

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Ubiquity.NET.Versioning

This repo includes automated Constrained Semantic Versioning (CSemVer) for MSBuild projects

Nuget PR/CI Workflow Status Release Workflow Status

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.

Overview

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.

Documentation

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.

Building the tasks

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.

About

Automated Constrained Semantic Versioning for Git repos

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • C# 68.2%
  • PowerShell 31.7%
  • CSS 0.1%