Semantic Versioning (SemVer)

Semantic Versioning (SemVer) is a versioning scheme that uses a three-part version number (MAJOR.MINOR.PATCH) to communicate the type of changes in a software release: breaking changes, new features, or bug fixes.

Category: General (also: Software Engineering)

Author: Atomic Glue Technical Team

## Definition

Semantic Versioning (SemVer) is a formal specification for software version numbers that communicates meaning about the underlying changes. Defined by Tom Preston-Werner at semver.org, SemVer uses the format MAJOR.MINOR.PATCH (e.g., 2.5.1). Increment the MAJOR version for incompatible API changes (breaking changes). Increment the MINOR version for backward-compatible new functionality. Increment the PATCH version for backward-compatible bug fixes. Pre-release versions can be appended with a hyphen and identifiers (e.g., 2.0.0-alpha.1). Build metadata can be appended with a plus sign (e.g., 2.0.0+build.20250703). SemVer is widely adopted across the software ecosystem, particularly in package management (npm, PyPI, Composer, Maven) where automated dependency resolution relies on version semantics.

## The SemVer Rules

The core rules of Semantic Versioning 2.0.0: 1. Software using SemVer MUST declare a public API. This API could be code, function signatures, or any defined contract. 2. MAJOR version (x.0.0): Increment when you make incompatible API changes. 3. MINOR version (0.x.0): Increment when you add backward-compatible functionality. 4. PATCH version (0.0.x): Increment when you make backward-compatible bug fixes. 5. Pre-release versions have lower precedence than the normal version. "1.0.0-alpha" < "1.0.0". 6. Version comparison is done left-to-right: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. 7. Once a versioned package is released, the contents of that version MUST NOT be modified. Any change MUST be a new version.

## Why SemVer Matters

SemVer solves a critical dependency management problem. Without it, developers cannot know whether upgrading a library will break their code. Package managers (npm, pip, bundler) use SemVer ranges to determine compatible versions: ^1.2.3 allows minor and patch updates but not major; ~1.2.3 allows only patch updates. This enables automated dependency updates with reasonable safety. SemVer also communicates intent to human consumers. Seeing a jump from 1.0.0 to 2.0.0 tells users to expect breaking changes and plan migration effort accordingly.

## Common SemVer Problems

SemVer relies on honest and accurate versioning, which is not always the reality. Common problems include: * **Accidental breaking changes in minor releases:** A developer adds a feature but unintentionally breaks backward compatibility. * **SemVer inflation:** Rapid MAJOR version bumps dilute the signal. Kubernetes went from 1.0 to 1.32 without breaking changes (they use MINOR for releases). * **Pre-release confusion:** The order of pre-release identifiers is lexicographic, not numeric. "alpha.2" sorts before "alpha.10" incorrectly. * **Abandonment of SemVer:** Some popular projects (like React) use 0.x for years, effectively nullifying the MAJOR signal. Despite these issues, SemVer remains the best system available and is essential for the modern package ecosystem.

## In code

Release types based on version change:

1.0.0 -> 1.0.1  # PATCH: Bug fix (backward compatible)
1.0.1 -> 1.1.0  # MINOR: New feature (backward compatible)
1.1.0 -> 2.0.0  # MAJOR: Breaking API change

Pre-release versions:
1.0.0-alpha.1  # First alpha
1.0.0-beta.1   # First beta
1.0.0-rc.1     # Release candidate 1
1.0.0          # Final release

## Common questions

Q: Does SemVer apply to applications or only libraries?

A: SemVer was designed for libraries and packages with a public API. Applications can use SemVer, but the MAJOR signal is less meaningful since applications have no published API contract.

Q: What does ~1.2.3 mean in npm?

A: It means "approximately equivalent to 1.2.3" and allows only patch-level changes (>=1.2.3 and <1.3.0). The caret ^1.2.3 allows minor-level changes (>=1.2.3 and <2.0.0).

Q: Can I modify a released version?

A: No. According to SemVer, once a version is released, its contents are immutable. Any change, however small, requires a new version. This is critical for reproducible builds.

## Key takeaways

• SemVer uses MAJOR.MINOR.PATCH to communicate breaking changes, features, and fixes.
• It enables automated dependency management with semantic range expressions.
• Honest versioning is critical; incorrect versioning breaks trust in the system.
• Pre-release identifiers (alpha, beta, rc) indicate incomplete but publishable versions.

## Related entries

• [Open Source](atomicglue.co/glossary/open-source)
• [Technical Debt](atomicglue.co/glossary/technical-debt)

Last updated July 2025. Permalink: atomicglue.co/glossary/semantic-versioning