Proposal

A path to Semantic Versioning 3.0.0

Semantic Versions ships as its own 1.0.0, but the ambition is bigger than that. We think it makes a good candidate for the next version of Semantic Versioning: the 3.0.0 that semver.org never got around to. We haven’t opened a pull request upstream; if there is enough interest, we will. Either way the spec stands on its own, so you can pick it up today whether or not that ever happens.

What we're proposing

Not a rewrite of 2.0.0.

There is not much here, and that is the point. Anything valid under Semantic Versioning 2.0.0 is still valid and parses the same way. The changes either put back meaning that a later draft stripped out, or write down the parts everyone was already using without a spec to point at.

01

Builds get their precedence back

2.0.0-rc.2 turned builds into inert "build metadata," so every build of a version counted as equal. This puts the rc.1 behaviour back: a build takes part in precedence and sorts above the plain release.

02

Patch, corrected

A patch is a fix for behaviour that was never meant to happen, not a promise of backward compatibility (which nothing can really guarantee). A fix stays a fix.

03

Sets, ranges and comparators, written down

Comparators, comparator sets, hyphen ranges, x-ranges, tilde, caret and the approximate operator (~>) all get defined, so two tools stop reading the same range two different ways.

Compared with 2.0.0

What changes, topic by topic.

A version that is valid under Semantic Versioning 2.0.0 is valid here and parses identically. Every difference is either additive or concerns the treatment of builds.

TopicSemantic Versioning 2.0.0Semantic Versions 1.0.0
Build precedenceIgnored: two versions differing only in build are equalParticipates in precedence, ranking above the plain release; a build is the antithesis of a pre-release
Build channelsBuild discarded during range resolutionBuild on a comparator/tilde/caret is a channel filter (^1.0.0+win)
Pre-release rangesAny pre-release on a comparator's tuple is admitted; opt in via a separate flagA pre-release is a prefix channel (^1.0.0-rc); wildcards -* / *-* replace the flag
SetsUndefinedDefined: ordered, unordered, normal, pre-release and build sets
Ranges & comparatorsOut of scopeDefined: comparators, comparator sets, and || unions
OperatorsNone< > = <= >=, plus advanced tilde/caret/hyphen/x-ranges
Approximate operatorNonePessimistic ~>, with its RubyGems meaning
GrammarProse + a single regexPublished BNF for versions, ranges and comparators

The one behavioural divergence to be aware of is build precedence: tooling that assumes builds are ignored will order build-bearing versions differently. This is deliberate. It is what lets extensions like Build Variants, Package Integrity and Dependency Locks carry meaning in the build. The history has the full story, and the FAQ covers the changes we deliberately didn't make.

Where it stands

We haven’t proposed this to semver/semver, and we aren’t opening a pull request for now. Semantic Versioning 2.0.0 has not meaningfully changed in over a decade, there is no obvious route to a 3.0.0, and the last attempt to add ranges (#584) stalled. If there is enough interest from package managers, registries and the people who maintain them, we will open that pull request and offer this as the basis for 3.0.0; say so in the repository. Until then, Semantic Versions keeps its own name and its own version: a finished spec you can use right now, with libraries in eight languages to match. Nothing here depends on semver.org taking it on.