{"canonical_url":"https://engineer.company/glossary/semantic-versioning/","content_markdown":"# Semantic versioning\n\n## What it is\n\nSemantic versioning, usually shortened to SemVer, is a set of rules for\nnumbering releases so that the number itself says what kind of change a release\ncontains. The specification, now at version 2.0.0 and originally written by Tom\nPreston-Werner, uses three numbers in the form MAJOR.MINOR.PATCH. A release that\nbreaks the public API raises the major number, one that adds functionality in a\nbackward-compatible way raises the minor number, and one that only fixes bugs\nwithout touching the API raises the patch number. When a number goes up, the\nnumbers to its right go back to zero, and each is compared as a number rather\nthan as text, so `1.10.0` comes after `1.9.0`.\n\nEverything rests on one requirement: the project must declare a public API, in\nthe code or in its documentation, because the numbers describe changes to that\nAPI and nothing else. Once a version is released, its contents must not change;\na correction is a new version. Major version zero, `0.y.z`, is for initial\ndevelopment, where anything may change at any time and the API should not be\nconsidered stable. Version `1.0.0` is the point at which the public API is\ndefined, and from then on the numbers follow how it changes.\n\nTwo optional labels extend the format. A pre-release goes after a hyphen and\nsorts before the release it leads up to, so `1.0.0-alpha` comes before\n`1.0.0-alpha.1`, which comes before `1.0.0-beta`, `1.0.0-rc.1` and finally\n`1.0.0`. Build metadata goes after a plus sign, as in `1.0.0+20130313144700`,\nand is ignored when versions are put in order, so two versions that differ only\nthere rank the same. A leading v, as in the Git tag `v1.2.3`, is not part of the\nsemantic version; the specification calls it a common way of marking a version\nnumber. Go makes it mandatory: a canonical Go module version is the letter v\nfollowed by a semantic version.\n\n## Why it matters\n\nThe specification starts from what it calls dependency hell. Specify\ndependencies too tightly and you get version lock, where upgrading one package\nmeans releasing new versions of everything that depends on it. Specify them too\nloosely and you get what the specification calls version promiscuity: accepting\nfuture releases without a sound basis for expecting compatibility. A version\nnumber with an agreed meaning lets a project state what it will accept: a\nlibrary that needs a function first added in 3.1.0 can accept anything from\n3.1.0 up to, but not including, 4.0.0, and take later fixes and additions\nwithout anyone editing the requirement.\n\nPackage managers act on that promise without asking. In Cargo, the Rust package\nmanager, a plain requirement such as `\"1.2.3\"` is a caret requirement and means\nat least 1.2.3 but below 2.0.0. When it writes `Cargo.lock`, Cargo picks the\ngreatest version inside that range, and it stays on the 1.x line after 2.0.0 is\npublished, because it treats 2.0.0 as incompatible. In node-semver, which calls\nitself the semantic versioner for npm, `^1.2.3` means `\u003e=1.2.3 \u003c2.0.0-0` and\n`~1.2.3` allows only patch-level changes, `\u003e=1.2.3 \u003c1.3.0-0`. Go builds the rule\ninto import paths: from major version 2 onward a module's path must end in a\nsuffix such as `/v2`, so two incompatible major versions are two different\nimport paths. Go's minimal version selection then takes, for each module, the\nhighest version that any requirement asks for, which is the minimum that\nsatisfies all of them. The result is not saved in a lock file; every\nmodule-aware command computes it again.\n\nNone of this makes the number a guarantee. It is a promise made by the people\nwho publish the package, and it is only as good as their judgement about what\ncounts as breaking, which is why Cargo publishes a long compatibility guide that\nsorts changes into major, minor and possibly-breaking. Most of that guide is\nabout changes that stop code that compiled yesterday from compiling today. The\nguide itself notes that almost every change carries some risk to runtime\nbehaviour, and that whether such a change is incompatible is usually a judgement\ncall for the maintainers.\n\n## What it looks like in practice\n\nFollow an invented Rust library, tally, through its releases. Version 0.4.2 is\nstill initial development. Version 1.0.0 declares the public API stable. Version\n1.0.1 fixes a rounding bug and is a patch. Version 1.1.0 adds a function,\n`parse_strict`, and marks the old `parse` as deprecated: the specification\nrequires a minor release for a deprecation and asks for at least one such\nrelease before the function is removed. Version 2.0.0 removes `parse` and is a\nmajor release. Version 2.1.0-rc.1 is a pre-release of the next minor version.\n\nAn application that depends on tally and three other invented crates states its\nrequirements in `Cargo.toml`. The comments give the range Cargo reads from each\nline:\n\n```toml\n[dependencies]\ntally = \"1.0.1\"         # \u003e=1.0.1, \u003c2.0.0: takes 1.1.0, never 2.0.0\nledger = \"0.4.2\"        # \u003e=0.4.2, \u003c0.5.0: 0.5.0 counts as breaking\nstamp = \"~1.2.3\"        # \u003e=1.2.3, \u003c1.3.0: patch releases only\nquill = \"=2.1.0-rc.1\"   # exactly this pre-release\n```\n\nThe `ledger` line shows a convention of the tools rather than of the\nspecification: Cargo treats the left-most non-zero number as the one that\nsignals a break, where the specification says everything below 1.0.0 may change\nat any time. Cargo leaves pre-releases out of a requirement unless it names one,\nso a requirement of `\"2.0\"` would never pick up tally's release candidate; the\nexact `=` form on the last line is the case where Cargo's documentation says a\nfully specified requirement might be warranted: depending on a pre-release while\navoiding breaking changes between pre-releases. Once resolved, the versions are\nrecorded in `Cargo.lock`, and `cargo update` moves them within these ranges.\nWith `--locked`, a build that would have to change the lock file returns an\nerror instead.\n\nWhat the number does not cover is anything outside the API. The\n[licence audit of 644 Rust crates](/portfolio/know-the-licence-of-everything-you-ship/),\ncarried out in September 2026, checks the licence of every crate on every build\nagainst an allow list, because a routine version bump deep in the dependency\ngraph can change what an application may be distributed under, silently, in a\nlock file that nobody reads in full. To prove the check works, it was made to\nfail twice on purpose. One test rewrote a crate's licence expression, the shape\nof a crate changing its terms upstream between versions, which human review\nmisses because the crate itself is not new. The other moved the pinned core\nrevision without regenerating the audit. A semantic version can tell you that\n1.4.0 is meant to work with code written against 1.0.0. It cannot tell you that\nyou may still ship it.\n\n## Where it goes wrong\n\n**A breaking change in a minor release.** It happens by accident or through a\ndifferent view of what counts as breaking. Cargo's guide lists changes that look\nharmless and are not: adding a variant to a public enum breaks code that matches\non it exhaustively, unless the enum was marked `#[non_exhaustive]` from the\nstart, and in rare cases involving glob imports even adding a new public item\ncauses a compile error. The specification's answer, once the mistake is noticed,\nis to release a new minor version that restores compatibility, never to modify\nthe release already published, and to tell users which version was at fault. On\nthe consuming side, a committed lock file and tests that run on every update are\nwhat catch it before production does.\n\n**Staying at 0.x for years.** Under the specification, major version zero\ncarries no stable API at all. Its FAQ is blunt: \"If your software is being used\nin production, it should probably already be 1.0.0.\" The tools fill the gap with\ntheir own convention: Cargo and node-semver treat the left-most non-zero number\nas the breaking one, so `^0.2.3` accepts only further 0.2.x releases and\n`^0.0.3` accepts no updates at all. A library that has sat at 0.x for years has\nusers who depend on it but no defined promise to them. Release 1.0.0 once people\nrely on the API; it changes a number, not the code.\n\n**Reading more into the number than it says.** Compatibility under the\nspecification is about the public API. Cargo's guide classes raising the minimum\nRust version a crate needs as possibly-breaking and generally recommends\ntreating it as a minor change, so a minor update can stop the build on an older\ntoolchain. Setting `package.rust-version` lets Cargo's resolver try older\nversions of the crate when needed. Licence terms, performance and behaviour the\nAPI never documented are outside the number altogether. Check them separately,\nwith a licence audit and tests, rather than inferring them from a minor release.\n\n**Two major versions in one build.** When two dependencies need incompatible\nversions of the same crate, say 0.6 and 0.7, Cargo builds both. The compiler\ntreats their types as different even when the names match. That usually shows up\nas a compile error and sometimes only at runtime: Cargo's documentation\ndescribes a downcast that fails because the object was created by a library\nusing version 1.0.0 while the calling code downcasts to the type from 2.0.0.\n`cargo tree -d` lists duplicate versions and where they come from. A library\nauthor can soften a major release with what Cargo's documentation calls the\nsemver trick: publish the new major version, then a point release of the old one\nthat re-exports the types from the new.\n\n## Further reading\n\n- [Semantic Versioning 2.0.0](https://semver.org/)\n  — the specification and its FAQ, including what to do after releasing a\n  breaking change by mistake.\n- [SemVer Compatibility](https://doc.rust-lang.org/cargo/reference/semver.html)\n  — the Cargo Book's guide to which changes in a Rust library are major, minor\n  or possibly-breaking, each with an example.\n- [Specifying Dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html)\n  — Cargo's requirement syntax: default, caret, tilde and comparison\n  requirements, and how pre-releases are matched.\n- [Dependency Resolution](https://doc.rust-lang.org/cargo/reference/resolver.html)\n  — how Cargo picks versions, what the lock file holds and the hazards of two\n  incompatible versions in one graph.\n- [node-semver](https://github.com/npm/node-semver) — the semantic versioner\n  for npm, with its caret, tilde and pre-release range rules.\n- [Go Modules Reference](https://go.dev/ref/mod) — major version suffixes, the\n  import compatibility rule and minimal version selection.\n\n\u003chttps://engineer.company/glossary/semantic-versioning/\u003e\n","date_modified":"2026-10-30T02:51:31Z","description":"What MAJOR.MINOR.PATCH promises, how Cargo, npm and Go act on it, and what a version number cannot tell you.","formats":{"gemtext":"https://engineer.company/glossary/semantic-versioning/index.gmi","gopher":"https://engineer.company/glossary/semantic-versioning/gophermap","html":"https://engineer.company/glossary/semantic-versioning/","json":"https://engineer.company/glossary/semantic-versioning/index.json","markdown":"https://engineer.company/glossary/semantic-versioning/index.md","pdf":"https://engineer.company/glossary/semantic-versioning/index.pdf"},"kind":"page","language":"en","title":"What is semantic versioning?","url":"https://engineer.company/glossary/semantic-versioning/","version":1}