SemVer (semantic versioning)

Semantic versioning (SemVer) is a convention for version numbers in the form MAJOR.MINOR.PATCH, where the number you change tells users what kind of release it is. A patch release fixes bugs, a minor release adds features without breaking anything, and a major release contains changes that can break existing users. The rules are published at semver.org.

How it works

Bump PATCH for backward-compatible bug fixes, MINOR for backward-compatible new features, and MAJOR for any incompatible change to the public API. Bumping a number resets the numbers to its right to zero. Versions below 1.0.0 are for initial development, where anything may change. A pre-release adds a suffix, as in 2.0.0-rc.1, and sorts before 2.0.0.

Starting from 1.4.2: a bug fix ships as 1.4.3. A new optional query parameter on an endpoint ships as 1.5.0, because existing clients keep working. Renaming a required field in a response ships as 2.0.0. A dependency range of ^1.4.2 accepts 1.4.3 and 1.5.0 but not 2.0.0, which is how package managers let you take fixes and features without taking breaking changes.

Why it matters in production

Versions matter most for what you deploy. The SRE bootcamp asks for container images tagged with semver and discourages latest, because latest is only the default tag name and moves with every push: two hosts pulling api:latest an hour apart can run different code, and a rollback has to guess which build it used to mean. Tag each image with its version, such as api:1.4.3, never overwrite a published tag, and roll back by deploying the previous version.