Semantic versioning

What it is

Semantic versioning, usually shortened to SemVer, is a set of rules
for numbering releases so that the number itself says what kind of
change a release contains. The specification, now at version 2.0.0
and originally written by Tom Preston-Werner, uses three numbers in
the form MAJOR.MINOR.PATCH. A release that breaks the public API
raises the major number, one that adds functionality in a
backward-compatible way raises the minor number, and one that only
fixes bugs without touching the API raises the patch number. When a
number goes up, the numbers to its right go back to zero, and each
is compared as a number rather than as text, so `1.10.0` comes after
`1.9.0`.

Everything rests on one requirement: the project must declare a
public API, in the code or in its documentation, because the numbers
describe changes to that API and nothing else. Once a version is
released, its contents must not change; a correction is a new
version. Major version zero, `0.y.z`, is for initial development,
where anything may change at any time and the API should not be
considered stable. Version `1.0.0` is the point at which the public
API is defined, and from then on the numbers follow how it changes.

Two optional labels extend the format. A pre-release goes after a
hyphen and sorts before the release it leads up to, so `1.0.0-alpha`
comes before `1.0.0-alpha.1`, which comes before `1.0.0-beta`,
`1.0.0-rc.1` and finally `1.0.0`. Build metadata goes after a plus
sign, as in `1.0.0+20130313144700`, and is ignored when versions are
put in order, so two versions that differ only there rank the same.
A leading v, as in the Git tag `v1.2.3`, is not part of the semantic
version; the specification calls it a common way of marking a
version number. Go makes it mandatory: a canonical Go module version
is the letter v followed by a semantic version.

Why it matters

The specification starts from what it calls dependency hell. Specify
dependencies too tightly and you get version lock, where upgrading
one package means releasing new versions of everything that depends
on it. Specify them too loosely and you get what the specification
calls version promiscuity: accepting future releases without a sound
basis for expecting compatibility. A version number with an agreed
meaning lets a project state what it will accept: a library that
needs a function first added in 3.1.0 can accept anything from

3.1.0 up to, but not including, 4.0.0, and take later fixes and
additions without anyone editing the requirement.

Package managers act on that promise without asking. In Cargo, the
Rust package manager, a plain requirement such as `"1.2.3"` is a
caret requirement and means at least 1.2.3 but below 2.0.0. When it
writes `Cargo.lock`, Cargo picks the greatest version inside that
range, and it stays on the 1.x line after 2.0.0 is published,
because it treats 2.0.0 as incompatible. In node-semver, which calls
itself the semantic versioner for npm, `^1.2.3` means `>=1.2.3
<2.0.0-0` and `~1.2.3` allows only patch-level changes, `>=1.2.3
<1.3.0-0`. Go builds the rule into import paths: from major version
2 onward a module's path must end in a suffix such as `/v2`, so two
incompatible major versions are two different import paths. Go's
minimal version selection then takes, for each module, the highest
version that any requirement asks for, which is the minimum that
satisfies all of them. The result is not saved in a lock file; every
module-aware command computes it again.

None of this makes the number a guarantee. It is a promise made by
the people who publish the package, and it is only as good as their
judgement about what counts as breaking, which is why Cargo
publishes a long compatibility guide that sorts changes into major,
minor and possibly-breaking. Most of that guide is about changes
that stop code that compiled yesterday from compiling today. The
guide itself notes that almost every change carries some risk to
runtime behaviour, and that whether such a change is incompatible is
usually a judgement call for the maintainers.

What it looks like in practice

Follow an invented Rust library, tally, through its releases.
Version 0.4.2 is still initial development. Version 1.0.0 declares
the public API stable. Version

1.0.1 fixes a rounding bug and is a patch. Version 1.1.0 adds a
function, `parse_strict`, and marks the old `parse` as deprecated:
the specification requires a minor release for a deprecation and
asks for at least one such release before the function is removed.
Version 2.0.0 removes `parse` and is a major release. Version
2.1.0-rc.1 is a pre-release of the next minor version.

An application that depends on tally and three other invented crates
states its requirements in `Cargo.toml`. The comments give the range
Cargo reads from each line:

```toml
[dependencies]
tally = "1.0.1"         # >=1.0.1, <2.0.0: takes 1.1.0, never 2.0.0
ledger = "0.4.2"        # >=0.4.2, <0.5.0: 0.5.0 counts as breaking
stamp = "~1.2.3"        # >=1.2.3, <1.3.0: patch releases only
quill = "=2.1.0-rc.1"   # exactly this pre-release
```

The `ledger` line shows a convention of the tools rather than of the
specification: Cargo treats the left-most non-zero number as the one
that signals a break, where the specification says everything below
1.0.0 may change at any time. Cargo leaves pre-releases out of a
requirement unless it names one, so a requirement of `"2.0"` would
never pick up tally's release candidate; the exact `=` form on the
last line is the case where Cargo's documentation says a fully
specified requirement might be warranted: depending on a pre-release
while avoiding breaking changes between pre-releases. Once resolved,
the versions are recorded in `Cargo.lock`, and `cargo update` moves
them within these ranges. With `--locked`, a build that would have
to change the lock file returns an error instead.

What the number does not cover is anything outside the API. The
licence audit of 644 Rust crates, carried out in September 2026,
checks the licence of every crate on every build against an allow
list, because a routine version bump deep in the dependency graph
can change what an application may be distributed under, silently,
in a lock file that nobody reads in full. To prove the check works,
it was made to fail twice on purpose. One test rewrote a crate's
licence expression, the shape of a crate changing its terms upstream
between versions, which human review misses because the crate itself
is not new. The other moved the pinned core revision without
regenerating the audit. A semantic version can tell you that

1.4.0 is meant to work with code written against 1.0.0. It cannot
tell you that you may still ship it.

Where it goes wrong

A breaking change in a minor release. It happens by accident or
through a different view of what counts as breaking. Cargo's guide
lists changes that look harmless and are not: adding a variant to a
public enum breaks code that matches on it exhaustively, unless the
enum was marked `#[non_exhaustive]` from the start, and in rare
cases involving glob imports even adding a new public item causes a
compile error. The specification's answer, once the mistake is
noticed, is to release a new minor version that restores
compatibility, never to modify the release already published, and to
tell users which version was at fault. On the consuming side, a
committed lock file and tests that run on every update are what
catch it before production does.

Staying at 0.x for years. Under the specification, major version
zero carries no stable API at all. Its FAQ is blunt: "If your
software is being used in production, it should probably already be
1.0.0." The tools fill the gap with their own convention: Cargo and
node-semver treat the left-most non-zero number as the breaking one,
so `^0.2.3` accepts only further 0.2.x releases and `^0.0.3` accepts
no updates at all. A library that has sat at 0.x for years has users
who depend on it but no defined promise to them. Release 1.0.0 once
people rely on the API; it changes a number, not the code.

Reading more into the number than it says. Compatibility under the
specification is about the public API. Cargo's guide classes raising
the minimum Rust version a crate needs as possibly-breaking and
generally recommends treating it as a minor change, so a minor
update can stop the build on an older toolchain. Setting
`package.rust-version` lets Cargo's resolver try older versions of
the crate when needed. Licence terms, performance and behaviour the
API never documented are outside the number altogether. Check them
separately, with a licence audit and tests, rather than inferring
them from a minor release.

Two major versions in one build. When two dependencies need
incompatible versions of the same crate, say 0.6 and 0.7, Cargo
builds both. The compiler treats their types as different even when
the names match. That usually shows up as a compile error and
sometimes only at runtime: Cargo's documentation describes a
downcast that fails because the object was created by a library
using version 1.0.0 while the calling code downcasts to the type
from 2.0.0. `cargo tree -d` lists duplicate versions and where they
come from. A library author can soften a major release with what
Cargo's documentation calls the semver trick: publish the new major
version, then a point release of the old one that re-exports the
types from the new.

Further reading

  * Semantic Versioning 2.0.0 — the specification and its FAQ,
including what to do after releasing a breaking change by mistake.

  * SemVer Compatibility — the Cargo Book's guide to which changes
in a Rust library are major, minor or possibly-breaking, each with
an example.

  * Specifying Dependencies — Cargo's requirement syntax: default,
caret, tilde and comparison requirements, and how pre-releases are
matched.

  * Dependency Resolution — how Cargo picks versions, what the lock
file holds and the hazards of two incompatible versions in one
graph.

  * node-semver — the semantic versioner for npm, with its caret,
tilde and pre-release range rules.

  * Go Modules Reference — major version suffixes, the import
compatibility rule and minimal version selection.

hThis page on the web	URL:https://engineer.company/glossary/semantic-versioning/	engineer.company	70
