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.
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
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.
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.
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”
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.
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.
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 ↓
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.
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.
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.
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.
1.0.0+build.1, 1.3.7+build.11.e0f985a1.0.0-alpha+001, 1.0.0+20130313144700See 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.