So far, the Kladde has no version. Every build is called 1.0.0, and whoever wants to know what's running in Azure can only guess. In this lesson, every build gets a version that comes from Git; the messages of the tender import become a package of their own, Kladde.Contracts, in a feed of its own; a worker uses this package in a fixed version; and /health says which version is answering.

SemVer

Semantic Versioning, SemVer for short, gives a version three numbers, MAJOR.MINOR.PATCH, and gives each a meaning:

Part Goes up when … Example
MAJOR a change breaks existing users 1.4.2 → 2.0.0
MINOR something new is added without breaking anything 1.4.2 → 1.5.0
PATCH a bug is fixed without a new feature 1.4.2 → 1.4.3

When one part goes up, those to its right fall back to 0. Two suffixes are added:

  • A prerelease version after a hyphen, such as 1.5.0-alpha.3. It comes before 1.5.0, and NuGet offers it only if you explicitly ask for it.
  • Build metadata after a plus sign, such as 1.5.0+5f1c2e7. It says what was built from, but doesn't count in comparisons.

A major version 0 (0.3.1) means, according to SemVer: nothing is promised yet, everything may change. For a package that only the Kladde itself uses, that is an honest start. As soon as others rely on it, it belongs at 1.0.0.

For a package with message types like Kladde.Contracts, "breaks existing users" is stricter than it sounds. A user is not just code that compiles the package, but also a message that is already in a queue, as JSON with the old names. A renamed property breaks both.