History

A short history of Semantic Versioning.

Semantic Versioning is well intentioned, but it carries a few bad definitions and a few missing ones. The most consequential mistake happened between two release candidates in 2013, and we still live with it today. Here is the paper trail, from the first commit of semver.org to the proposal that never landed.

Dec 2009 · semver.org · @mojombo

Versioning gets a name

Tom Preston-Werner, a cofounder of GitHub, publishes Semantic Versioning: a name, a specification and a URL for the MAJOR.MINOR.PATCH convention many projects already followed loosely. The pitch is dependency hell: with a public API declared and the three numbers meaning what they say, a consumer can state what it needs and a tool can resolve it. The CommonJS group is discussing whether to require it the same day. Within days it has “special versions” (1.0.0beta1), the ancestor of pre-releases.

semver.org@ca64580 — “First commit” · semver.org/spec/v0.9.0.html

Jan 2010 · npm · @isaacs

npm makes it the rule

npm arrives, adopts Semantic Versioning for package versions from the start, and nests node_modules, so conflicting transitive dependencies can be installed side by side instead of fighting over one slot. JavaScript sidesteps the first circle of dependency hell that trapped single-version ecosystems, and the registry goes on to hold more packages than anywhere else. Every one of them is versioned by this spec, which makes npm the spec’s largest test, and the place its gaps show first.

Feb 2011 · node-semver · @isaacs

npm writes down how to match versions

Isaac Z. Schlueter publishes the semver package for npm. Over the following years it defines what the spec never did: comparators, x-ranges, tilde, caret and hyphen ranges, ||, a rule for when pre-releases match, and a published Backus–Naur grammar for ranges. Every ^1.2.3 in a package.json is written in its language, and much of the range grammar in Semantic Versions descends from it.

npm/node-semver

Mar–Jun 2011 · 1.0.0

1.0.0, and pre-releases get their dash

The document becomes Semantic Versioning 1.0.0. Special versions are renamed pre-releases, and in June they get the dash that every parser now expects: 1.0.0-alpha1 rather than 1.0.0alpha1. Precedence is still “lexicographic ASCII sort order”, which is why 1.0.0-beta11 would sort before 1.0.0-beta2; the dotted identifiers that fix that are still a few months away.

semver.org/spec/v1.0.0.html · semver@05a00df — “Delimit pre-release versions by dash”

Nov 2011 · @mojombo

Builds are introduced

Tom Preston-Werner adds build versions to the spec. A build functions as the antithesis of a pre-release (you could call it a post-release) and it participates in precedence. Two builds of the same normal version can be ordered.

semver@7092112 — "add build versions"

Dec 2011 · 2.0.0-rc.1

The high-water mark

2.0.0-rc.1 is published. As far as we can tell it is the most accurate versioning spec to date: it encompasses common practice of generating builds and build variants, and keeps their precedence intact. This is the document Semantic Versions takes as its starting point.

semver.org/spec/v2.0.0-rc.1.html

Mar 2013 · 2.0.0-rc.2 · @haacked & @jeffhandley

Builds become inert "build metadata"

Two years later, Phil Haack and Jeff Handley, contributors from the NuGet and .NET ecosystem, redefine builds as build metadata and strip away their precedence. Overnight, every version with build metadata becomes equivalent to any other of the same normal or pre-release version. Six artifacts with different git hashes and architectures are now semantically identical, with no way in the spec to order or choose between them. See the exact wording that changed ↓

rc.1 → rc.2 diff · semver/semver#77 · 57fd194 · 13aaada

Jun 2013 · 2.0.0

2.0.0 is final. Then nothing.

2.0.0 is published on 18 June 2013 with rc.2’s definitions intact: build metadata is ignored for precedence, and the spec still says nothing about ranges. It is the version every package manager cites today. In the years since, the document has gained a grammar, a regex and translations, but no change to what a version means, and no successor has been published.

semver.org/spec/v2.0.0.html

Since 2013

npm forgets builds exist

npm's own SemVer implementation, which itself adds grammars and logic on top of the spec, defaults to stripping build metadata from versions. The result: there are effectively no packages in the registry carrying build metadata, even though it is supposed to be a valid part of a version. A legitimate, useful concept was co-opted into a non-functional one, confusing tooling authors ever since.

Jun 2020 · semver/semver#584 · @isaacs

Ranges are proposed upstream, and stall

Isaac proposes a specification for ranges to Semantic Versioning itself: a draft of about 380 lines covering comparators, caret, tilde, x-ranges, hyphen ranges, || and node-semver’s pre-release rule. Maintainers from Cargo, Composer, RubyGems, Bundler and CocoaPods point out where their tools behave differently, and that aligning them would break constraints already in the wild. After 79 comments the pull request is still open, and the spec still has no ranges.

semver/semver#584

Today · 1.0.0

Semantic Versions

Semantic Versions reverts the build change, restores build precedence, corrects the definition of a patch, and finally writes down the sets, ranges and comparators the ecosystem already relies on, building on node-semver’s grammar and extending it with channels, wildcards and contexts. If we want to avoid becoming heretics in the sixth circle, we have to codify what we actually do. It is also written to become Semantic Versioning 3.0.0, the successor 2.0.0 never got, if there is enough interest in taking it upstream.

The exact change

Two sentences, a decade of confusion.

The intent of the + build was never in doubt in 2.0.0-rc.1: a build was a post-release that ordered above its normal version. Between the two release candidates, the sentence that gave it meaning was struck and replaced. Here is that change, as a diff of the verbatim spec text.

SEMVER.md 2.0.0-rc.1 → 2.0.0-rc.2 +6−5
@@ -33,3 +31,4 @@ Build definition
33-A build version MAY be denoted by appending a plus sign …
34-Build versions satisfy and have a higher precedence than the associated normal version.
35-Examples: 1.0.0+build.1, 1.3.7+build.11.e0f985a
31+Build metadata MAY be denoted by appending a plus sign …
32+Build metadata SHOULD be ignored when determining version precedence.
33+Thus two packages with the same version but different build metadata are considered to be the same version.
34+Examples: 1.0.0-alpha+001, 1.0.0+20130313144700
@@ -40,2 +38,2 @@ Precedence
40-Precedence MUST be calculated by separating the version into major, minor, patch, pre-release, and build identifiers in that order. …
41-Pre-release and build version precedence MUST be determined by comparing each dot separated identifier.
38+Precedence MUST be calculated by separating the version into major, minor, patch and pre-release identifiers in that order.
39+(Build metadata does not figure into precedence.) …

See the full side-by-side: rc.1 → rc.2 diff · rc.1 text · rc.2 text

Why they did it, and the opening it left

It wasn't malice; it answered a real need. NuGet was designing its v3 feed and wanted build metadata to be diagnostic only: a commit hash, date, or build number that never changes a package's identity. If build affected precedence, then 1.0.0+a and 1.0.0+b would be different packages: ambiguous equality, duplicate registry entries, and unpredictable folder paths, URLs and .nupkg filenames that NuGet constructs from the normalized version. Declaring build “ignored” made identity deterministic. That local win became the global default, and npm's own SemVer, which strips build, sealed it.

The irony is the opportunity. Because the ecosystem then stopped using build at all, the slot is empty real estate. Semantic Versions restores its precedence and puts it to work exactly where nothing else lives: Build Variants, Package Integrity and Dependency Locks are what a meaningful build was always for.

Reasoning drawn from “Supporting Semantic Versioning 2.0.0” (.NET Blog) and the NuGet SemVer 2.0.0 support notes.