Semantic Versioning (SemVer)
Semantic Versioning (SemVer) is a versioning scheme that uses a three-part `MAJOR.MINOR.PATCH` number to communicate the nature of changes in each release. MAJOR increments signal breaking changes that require consumer updates. MINOR increments add backward-compatible functionality. PATCH increments fix bugs in a backward-compatible way. The specification is maintained at semver.org and is the standard for software libraries, package registries (npm, Maven, PyPI), and many REST APIs.
Formula
MAJOR: breaking changes. MINOR: new features, backward compatible. PATCH: bug fixes, backward compatible.Why it matters in practice
SemVer transforms version numbers from arbitrary labels into communication about compatibility. A consumer that pins `^2.3.0` (npm-style caret range) is saying "I accept any 2.x.y where x≥3 or y≥0" — it will automatically receive MINOR and PATCH updates but be protected from MAJOR breaking changes. This contract only holds if the API provider follows SemVer faithfully. A MINOR bump that introduces a breaking change breaks the contract and can cause silent production failures in consumers that auto-update.
Common mistakes
- •Treating SemVer as just a numbering scheme rather than a compatibility contract — the meaning of MAJOR/MINOR/PATCH is the value, not the numbers.
- •Using SemVer for REST APIs that are versioned by URL (v1, v2) — URL versioning and SemVer are different models; mixing them creates confusion about what a "v1.2.3" URL means.
- •Not communicating breaking changes in release notes even when incrementing MAJOR — the MAJOR bump signals "something broke", but consumers need to know what specifically changed.
Related Terms
Major, minor, and patch bumps (API)
Patch fixes bugs, Minor adds features, Major breaks compatibility.
Breaking change (API)
Modification causing existing clients to fail or require updates.
API deprecation strategy
Plan for retiring API while giving consumers migration time.
Calendar Versioning (CalVer)
Version tied to release dates rather than compatibility signals.