Skip to content

Semantic Versioning

In one line

Semantic Versioning (SemVer) numbers releases as MAJOR.MINOR.PATCH, where each segment signals the kind of change.

In simple words

Semantic Versioning (SemVer) is a version numbering scheme: MAJOR.MINOR.PATCH. Given a version 2.4.1: MAJOR (2) changes on incompatible API changes, MINOR (4) changes on backward-compatible new features, and PATCH (1) changes on backward-compatible bug fixes. A pre-release appends -alpha, -beta, -rc.1; build metadata appends +sha.

The promise is that a consumer can safely update to a higher PATCH or MINOR without breaking, and knows that a higher MAJOR requires checking the migration guide. This enables automated dependency updates and range expressions like ^1.2.3 (any 1.x.x ≥ 1.2.3) or ~1.2.3 (any 1.2.x ≥ 1.2.3).

SemVer pairs naturally with Conventional Commits: a feat commit bumps MINOR, a fix bumps PATCH, and a BREAKING CHANGE bumps MAJOR. Tools like semantic-release automate this. SemVer is widely adopted in npm, Cargo, and many package ecosystems.

Example

bash
# Version progression example
1.0.0   # initial release
1.0.1   # bug fix → PATCH bump
1.1.0   # new feature, backward compatible → MINOR bump
2.0.0   # breaking API change → MAJOR bump
2.0.0-alpha.1  # pre-release of 2.0.0
2.0.0+sha.abc  # build metadata

# npm range expressions
^1.2.3  # >=1.2.3 <2.0.0 (any 1.x.x at or above 1.2.3)
~1.2.3  # >=1.2.3 <1.3.0 (any 1.2.x at or above 1.2.3)

MAJOR breaks API, MINOR adds compatible features, PATCH fixes bugs. ^ and ~ in package.json express compatible ranges.

Related terms

Related Resources

Related Lessons

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to glossary