https://github.com/ubiquitydotnet/csemver.gitbuild
Automated Constrained Semantic Versioning for Git repos
https://github.com/ubiquitydotnet/csemver.gitbuild
assemblyversion buildversion csemver msbuild-task semver
Last synced: 12 months ago
JSON representation
Automated Constrained Semantic Versioning for Git repos
- Host: GitHub
- URL: https://github.com/ubiquitydotnet/csemver.gitbuild
- Owner: UbiquityDotNET
- License: mit
- Created: 2017-09-17T18:09:03.000Z (over 8 years ago)
- Default Branch: develop
- Last Pushed: 2025-06-22T20:33:39.000Z (12 months ago)
- Last Synced: 2025-06-22T21:28:18.706Z (12 months ago)
- Topics: assemblyversion, buildversion, csemver, msbuild-task, semver
- Language: C#
- Homepage: https://ubiquitydotnet.github.io/CSemVer.GitBuild/
- Size: 6.38 MB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Ubiquity.NET.Versioning
This repo includes support for versioning numbers. This support includes:
1) Automated Constrained Semantic Versioning ([CSemVer](https:/csemver.org)) for MSBuild
projects.
2) A standalone library useful for parsing, sorting and validating versions.
- [SemVer](https://semver.org)
- [CSemVer](https://csemver.org)
- This is a Constrained Semantic Version (That is, a strict subset of a SemVer)
- [CSemVer-CI](https://csemver.org)
- This is also a Constrained Semantic Version but is designed for ***POST-RELEASE** CI
build numbering. It is NOT a CSemVer but IS a SemVer.
>[!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 versions that includes a number of unit tests to ensure it is
> operating correctly.
## Status
## 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](http://csemver.org) (CSemVer).
## Constrained use of Constrained Semantic Versions
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 automated builds (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](https://ubiquitydotnet.github.io/CSemVer.GitBuild/)
>[!WARNING]
> The formal 'spec' for [CSemVer](https://csemver.org) remains silent on the point of the short
> format.^1^ Instead it relies on only examples. However, the examples are inconsistent on the
> requirement of a delimiter between the short name and number components of a version. It
> shows two examples '1.0.0-b03-01' ***AND*** '5.0.0-r-04-13'. So, which is it? Is the
> delimiter required or not?
>
> This may seem like an entirely academic issue, but when parsing an input it impacts the
> validity of inputs. Also, when the dealing with ordering and the length of otherwise equal
> components comes into play it can impact the behavior as well. How are `1.0.0-b03-01` and
> `1.0.0-b-03-01` ordered in relation to each other? Is the former even a valid CSemVer?
>
> This implementation is assuming the former is a typographical error and a delimiter is
> required in all cases. ***That is, `1.0.0-b03-01` is not a valid CSemVer.***
## 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](https://github.com/CK-Build/csemver.org/issues/2) which was reported upon
testing this library and found inconsistencies.