Semantic Versioning
PATCH, to communicate what kind of changes a new software release contains and whether it is safe to upgrade to.
Definition
Semantic versioning (SemVer) is a versioning convention that uses a three-part number, MAJOR.MINOR.PATCH, to communicate what kind of changes a new software release contains and whether it is safe to upgrade to.
Overview
Under semantic versioning, a version number like 2.4.1 breaks down into three parts with specific meaning: the MAJOR number increases when a release contains incompatible, breaking API changes; the MINOR number increases when new functionality is added in a backward-compatible way; and the PATCH number increases for backward-compatible bug fixes only. This shared convention lets package managers and developers reason about upgrade risk from the version number alone, without reading every changelog in detail. Most package managers use SemVer ranges to automate safe upgrades: a dependency declared as `^2.4.1` in npm, for example, allows automatic upgrades to any 2.x.x release but not to 3.0.0, on the assumption that minor and patch releases will not break existing code. This convention underpins much of the modern open-source ecosystem, since library authors who follow SemVer give downstream consumers confidence that most updates can be applied without manual review, reserving careful testing for major version bumps. Semantic versioning is a social contract as much as a technical one — it only works if maintainers correctly classify their own changes, and violations (a “breaking change” mistakenly shipped as a patch) can cascade through the dependency graphs of every project that depends on that package. Pre-1.0.0 releases (0.x.y) are treated as an exception under the SemVer spec, signaling that the API is still unstable and any change, including breaking ones, may occur in a minor release. It is often mentioned alongside Monorepo in this space. It is often mentioned alongside Pull Request in this space.
Key Concepts
- Uses a MAJOR.MINOR.PATCH version number format
- MAJOR bumps signal breaking, backward-incompatible changes
- MINOR bumps signal new, backward-compatible functionality
- PATCH bumps signal backward-compatible bug fixes
- Enables package managers to safely automate minor and patch upgrades
- Widely adopted across npm, PyPI, Cargo, and most open-source ecosystems
- Pre-1.0.0 releases are treated as unstable under the specification
Use Cases
Frequently Asked Questions
From the Blog
API Design Principles: Resources, Contracts, Versioning
An API is a contract you will be held to long after the code behind it is rewritten, so design decisions about resources, errors, pagination and versioning outlive almost everything else you build. This guide covers the choices that determine whether clients break when you change things.
Read More ProgrammingGo modules explained: versioning, upgrades and vendoring
Work with Go modules deliberately. Minimal version selection is why your build does not drift and why an upgrade is an explicit edit, go.sum is an integrity record rather than a lockfile, and the major-version-in-the-path rule is what makes breaking upgrades survivable.
Read More AI & TechnologySemantic Search Explained: Beyond Keywords
Semantic search finds results by meaning rather than exact words, using vector embeddings so a query and a relevant document match even with no shared terms.
Read More AI & TechnologyWhat Is Semantic Search and How Does It Work?
Semantic search finds results by meaning, not keywords, using embeddings to represent text as vectors and matching queries to the closest ones in vector space.
Read More