This version is deprecated. v1.0.0-beta.1 defines names for the different kind of versions (Official Releases with Major/Minor/Patch Release, Pre Releases with Main/Numbered/Patch PreRelease and Post Releases for CSemVer-CI).
CSemVer is an operational subset of Semantic Versioning 2.0.0 (http://semver.org) that is defined around one strong idea:
CSemVer versions are totally ordered, each version corresponds to a unique 64 bits unsigned integer ranging
from 1 (v0.0.0-alpha) to 13000100000000000000 (v99999.99999.9999).
A version can be "normal" (1.2.3), pre release (1.2.3-beta), numbered pre release (1.2.3-rc.3) and
fix of a pre release (1.2.3-alpha.1.1).
CSemVer-CI is an extension that supports CI builds. Its versions follow SemVer 2.0.0, but are not CSemVer compliant. CSemVer-CI defines 2 kind of CI versions:
1 - CSemVer defines a totally ordered set of versions. This is used to generate version names that guaranty a correct application of precedence rules.
| CSemVer | NuGet V2(1) | Ordered Version | Description |
|---|---|---|---|
| v0.0.0-alpha | 0.0.0-a | 1 | The very first possible version is the 0.0.0 alpha prerelease. There are 42 possible first versions (it can be 0.0.0, 0.1.0 and 1.0.0 with their 13 prereleases). |
| v0.0.0-alpha.1 | 0.0.0-a01 | 101 | These are numbered prerelease. There can be 99 numbered prereleases. |
| v0.0.0-alpha.2 | 0.0.0-a02 | 201 | |
| v0.0.0-alpha.0.1 | 0.0.0-a00-01 | 2 | Oops! There was a bug in the very first alpha and someone, for any reason, needs a fix. |
| v1.0.0 | 1.0.0 | 130001000130001 | The first official version. |
| v1.0.1 | 1.0.1 | 130001000260002 | A fix to the first official version: it contains only bug fixes, no breaking changes. |
| v1.1.0 | 1.1.0 | 130002300140001 | Introduction of new features but no breaking changes. |
| v2.0.0-rc | 2.0.0-r | 260002000120001 | Preparing the next major version. |
(1) The NuGet packaging system in its V2 version (2015) do not follow Semantic Versioning (the 'special name' - the prerelease part - is simply ordered lexically in ASCII sort order). Moreover this 'special name' can not exceed 20 characters. The latter is the reason why the NuGet V2 package name uses only the initial of the prerelease name (in order to support CSemVer-CI LastReleasedBased versionnig).
2 - CSemVer makes possible to really control the versions that are published. The valid successors (according to Semantic Versioning rules) of any version can be computed (there can be up to 43 successors to a version) and, respectively, one can decide whether a version is a valid predecessor of any other version.
| Version | Successors |
|---|---|
| v1.2.3 42 successors |
v1.2.4-alpha, v1.2.4-beta, v1.2.4-chi, v1.2.4-delta, v1.2.4-epsilon, v1.2.4-gamma, v1.2.4-iota, v1.2.4-kappa, v1.2.4-lambda, v1.2.4-mu, v1.2.4-omicron, v1.2.4-prerelease, v1.2.4-rc, v1.2.4, v1.3.0-alpha ⇒(2) v1.3.0-rc, v1.3.0, v2.0.0-alpha ⇒ v2.0.0-rc, v2.0.0 |
| v1.2.3-alpha 43 successors |
v1.2.3-alpha.0.1, v1.2.3-alpha.1, v1.2.3-beta ⇒ v1.2.3-rc, v1.2.3, v1.3.0-alpha ⇒ v1.3.0-rc, v1.3.0, v2.0.0-alpha ⇒ v2.0.0-rc, v2.0.0 |
| v1.2.3-delta.5 40 successors |
v1.2.3-delta.5.1, v1.2.3-delta.6, v1.2.3-epsilon ⇒ v1.2.3-rc, v1.2.3, v1.3.0-alpha ⇒ v1.3.0-rc, v1.3.0, v2.0.0-alpha ⇒ v2.0.0-rc, v2.0.0 |
| v1.2.3-prerelease.2.3 32 successors |
v1.2.3-prerelease.2.4, v1.2.3-prerelease.3, v1.2.3-rc, v1.2.3, v1.3.0-alpha ⇒ v1.3.0-rc, v1.3.0, v2.0.0-alpha ⇒ v2.0.0-rc, v2.0.0 |
| v1.2.3-rc 31 successors |
v1.2.3-rc.0.1, v1.2.3-rc.1, v1.2.3, v1.3.0-alpha ⇒ v1.3.0-rc, v1.3.0, v2.0.0-alpha ⇒ v2.0.0-rc, v2.0.0 |
(2) The ⇒ replaces the list of the prerelease names from alpha, beta, chi, delta, epsilon, gamma, iota, kappa, lambda, mu, omicron, prerelease up to rc.
3 - CI builds correspond to productions that are not actual releases: the version has to be automatically created since no real version exist for them. A CI build is defined by: a CIBuildName that identifies the source, the nature, or any other constant key of the build (this is usually the name of the 'branch' in a SCM) and a BuildIndex that is a number or an identifier that gets bigger for each new build (it is usually a simple integer that is provided by the CI process or a timestamp).
CSemVer-CI enables the support of CI buils into CSemVer versions with the guaranty of a valid precedence order (in order to secure deployments). The two kind of versions offers two different guaranties:
The table below helps understand how CSemVer-CI LastReleasedBased works.
| Base Version | CI Version | Immediate successor | Description |
|---|---|---|---|
| v0.4.1-rc.2.1 | 0.4.1-rc.2.1.ci-develop.15 | v0.4.1-rc.2.2 |
This is the simplest one: by appending a dotted part, the CI version has a greater precedence than its base.
"Base Version" < "CI Version" < "Immediate successor" is guaranteed here and for the 3 other cases below.0 |
| v3.2.1-rc.1 | 3.2.1-rc.1.0.ci-develop.15 | v3.2.1-rc.1.1 | It is the "padding" with the .0 here that does the job. |
| v3.2.1-beta | 3.2.1-beta.0.0.ci-develop.15 | v3.2.1-beta.0.1 | A double padding is required for pre release. |
| v1.2.3 | 1.2.4--ci-develop.15 | 1.2.4-alpha | This uses the double dash trick of the ZeroBased kind, plus another one: the Patch is incremented by one. |
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
CSemVer versions follow Semantic Versioning 2.0.0 rules but adds some constraints to them.
Syntax of a CSemVer MUST be:
[v|V]Major.Minor.Patch[-PreReleaseName[.PreReleaseNumber[.PreReleaseFix]]][+BuildMetaData]
CSemVer versions MAY be prefixed with a 'v' or 'V' (GitHub convention). This is the only extension that is not supported by SemVer.
The Major part MUST be defined between 0 and 99999.
The Minor part MUST be defined between 0 and 99999.
The Patch part MUST be defined between 0 and 9999.
The PrereleaseName MAY be denoted by appending a hyphen and a name that MUST be one of the 13 values of the following list (ordered from 0 to 12): alpha, beta, chi, delta, epsilon, gamma, iota, kappa, lambda, mu, omicron, prerelease, rc.
The PrereleaseName's intial MAY be used as a short form: a, b, c, d, e, g, i, k, l, m, o, p, r.
Any other name not listed in this set MUST be either mapped to/considered as "prerelease" OR considered syntactically invalid.
The PrereleaseNumber MAY be denoted by appending a dot and a number that MUST be defined between 0 and 99.
The PrereleaseFix MAY be denoted by appending a dot and a number that MUST be defined between 1 and 99.
The PrereleaseNumber 0 MUST appear only when a PrereleaseFix is specified to denote a fix of a first prerelease (v4.3.2-rc.0.2 is the second fix of v4.3.2-rc).
CSemVer-CI versions follow Semantic Version 2.0.0 rules.
Syntax of a CSemVer-CI ZeroTimed MUST be:
0.0.0--CIBuildName-BuildIndex[+BuildMetaData]
The CIBuildName MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-] and MUST NOT be empty.
The BuildIndex MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-] and MUST NOT be empty. It can be purely numeric.
BuildIndex MUST increase between builds. It MAY be time based with a fixed format (ie. YYYYMMDD-HHMMSS), be an incremented number provided by the CI process or any other numeric or alphanumeric value as long as it is increasing (either numerically or lexically in ASCII sort order) for each build.
Syntax of a CSemVer-CI LastReleasedBased MUST be:
Applied to a vMajor.Minor.Patch version:
Major.Minor.Patch+1--ci-CIBuildName.BuildIndex
Applied to a vMajor.Minor.Patch-PreReleaseName version:
Major.Minor.Patch+1-PreReleaseName.0.0.ci-CIBuildName.BuildIndex
Applied to a vMajor.Minor.Patch-PreReleaseName.PreReleaseNumber version:
Major.Minor.Patch+1-PreReleaseName.PreReleaseNumber.0.ci-CIBuildName.BuildIndex
Applied to a vMajor.Minor.Patch-PreReleaseName.PreReleaseNumber.PreReleaseFix version:
Major.Minor.Patch+1-PreReleaseName.PreReleaseNumber.PreReleaseFix.ci-CIBuildName.BuildIndex
The Constrained Semantic Versioning specification is authored by Invenietis.
If you'd like to leave feedback, please open an issue on GitHub.