🔢Semantic Versioning

NEW

Also known as: SemVer

A versioning convention using MAJOR.MINOR.PATCH to communicate compatibility and changes.

DESCRIPTION

Semantic Versioning is a formal scheme for version numbers that signal compatibility and change scope. MAJOR increments indicate incompatible API changes, MINOR adds backward-compatible functionality, and PATCH includes backward-compatible bug fixes. It provides predictable dependency management and reduces integration risks across ecosystems. Widely adopted in package managers and CI/CD pipelines, SemVer clarifies upgrade implications for consumers.

ALTERNATIVE DEFINITIONS

SemVer

Given a version number MAJOR.MINOR.PATCH, increment the MAJOR version when you make incompatible API changes, the MINOR version when you add functionality in a backward compatible manner, and the PATCH version when you make backward compatible bug fixes.

Canonical rule specifying MAJOR, MINOR, PATCH semantics.

Source

Wikipedia

Semantic versioning is a versioning scheme that conveys meaning about the underlying changes with a version number format of MAJOR.MINOR.PATCH.

Summarizes SemVer as meaning-carrying version numbers.

Source

npm

Semantic versioning, or SemVer, is a specification that uses a three-part version number to indicate the type of changes in a package and their impact on compatibility.

Relates SemVer directly to package dependency management.

Source

RELATED TERMS

Version Control API Compatibility Schema Evolution Audit Trail Dependency Management Releasing Package Management Structural Changes Git Software Lifecycle

COMPETING TERMS

Calendar Versioning

RELATIONS

• Broader: Versioning

KNOWLEDGE AREAS

Software Engineering Platform & Tooling Collaboration Testing & Validation

TARGET AUDIENCE

Software Developer DevOps Engineer Software Architect Product Owner IT Manager

EXTERNAL SOURCES

• Wikipedia - Software versioning#Semantic versioning
• SemVer - Official specification version 2.0.0
• npm - npm semver range documentation
• Python Packaging Authority - Version metadata in Python packaging
• Git - Release and tagging practices

TOP QUESTIONS

Why use Semantic Versioning for APIs?

Semantic Versioning signals breaking changes via MAJOR increments, enabling safe client upgrades and automated dependency management across ecosystems.

Category: Relevancy

What constitutes a MAJOR version bump in Semantic Versioning?

Any incompatible API change, such as removing endpoints or altering input/output contracts, requires incrementing MAJOR.

Category: Requirements

How does Semantic Versioning differ from Calendar Versioning?

SemVer encodes compatibility and change scope; CalVer encodes release dates. SemVer is better for dependency resolution and automated upgrades.

Category: Alternatives

What are common mistakes in Semantic Versioning?

Mislabeling breaking changes as MINOR or PATCH, skipping changelogs, and ignoring pre-release metadata semantics cause confusion and break builds.

Category: Mistakes

How should pre-release versions be handled in Semantic Versioning?

Use identifiers like -alpha, -beta, -rc to denote unstable releases. Order is lexicographic and follows SemVer precedence rules.

Category: BestPractice

What risks arise from poor Semantic Versioning discipline?

Downstream breakages, dependency hell, and rollback complexity can occur, undermining trust and velocity.

Category: Risk

How to adopt Semantic Versioning in CI/CD?

Automate version bumps via commit conventions, generate changelogs, and enforce checks on breaking changes through contract tests.

Category: Management

Is Semantic Versioning suitable for machine learning models?

Yes, use MAJOR for incompatible schema or interface changes, MINOR for new features, PATCH for fixes, plus model cards documenting changes.

Category: Opinion

What is the biggest misunderstanding about Semantic Versioning?

Some think any new feature is a MAJOR bump; actually, backward-compatible additions are MINOR.

Category: Misunderstanding