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
A version number under SemVer is a compatibility promise, not a label. 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 auto-receives MINOR and PATCH updates but is shielded from MAJOR breaks. The promise only holds if the provider follows SemVer faithfully: ship a breaking change in a MINOR bump and you silently break every consumer that auto-updates. That single mistake is how a routine dependency upgrade takes down production.
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.