In Semantic Versioning, the three core numbers—MAJOR.MINOR.PATCH—signal the compatibility impact of a release: breaking public API changes, backward-compatible additions, or backward-compatible bug fixes. The format helps people judge upgrades, but it is a convention about a project’s declared public API, not a guarantee that every update will be trouble-free.
What do the three numbers in a SemVer version mean?
The Semantic Versioning 2.0.0 specification defines the core format as MAJOR.MINOR.PATCH. Each position answers a different compatibility question:
As an Amazon Associate I earn from qualifying purchases.
| Part | When it increases | Example |
|---|---|---|
| MAJOR | A change breaks compatibility with the declared public API. | 2.3.4 to 3.0.0 |
| MINOR | New backward-compatible functionality is added to the public API, or public API functionality is marked deprecated. | 2.3.4 to 2.4.0 |
| PATCH | A backward-compatible bug fix is made. | 2.3.4 to 2.3.5 |
These are illustrative version changes, not examples of particular product releases. As the specification puts it, “MAJOR version when you make incompatible API changes, MINOR version when you add functionality in a backwards compatible manner, and PATCH version when you make backwards compatible bug fixes.”
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Why are there three parts?
The three positions give maintainers and users a compact way to communicate what kind of change a release contains and how it may affect software that depends on it. A user evaluating an upgrade can distinguish a declared compatibility break from a compatible API addition or a bug fix, rather than infer the change from the size of the number alone.
#1 Best Overall
This signal works only in relation to a defined public API. Siemens’ API versioning guidance likewise frames major changes around their effect on existing API clients. SemVer does not automatically classify every change to an application’s interface, data, deployment, or internal implementation; those matter to the version only insofar as they are part of the project’s declared public API.
How do the numbers change between releases?
When a component increases, the components to its right reset to zero. A minor release resets the patch number; a major release resets both minor and patch numbers.
- For a backward-compatible bug fix, increase PATCH:
2.3.4becomes2.3.5. - For backward-compatible public API functionality or a public API deprecation, increase MINOR and set PATCH to zero:
2.3.5becomes2.4.0. - For a backward-incompatible public API change, increase MAJOR and set MINOR and PATCH to zero:
2.4.0becomes3.0.0.
The classification depends on compatibility, not on how ambitious a change sounds. A large internal refactor that preserves the public API and fixes incorrect behavior can be patch-level; a small change to an API signature that breaks existing clients can be major-level.
Does a minor or patch update guarantee compatibility?
No. SemVer describes what maintainers promise about changes to their public API when they follow the convention. It cannot establish that the project has implemented that promise correctly, that your use of the software matches the documented API, or that the upgrade has no defects. A study indexed by arXiv in 2022 discusses abnormal execution and crashes after upgrades labeled as compatible: “Has My Release Disobeyed Semantic Versioning? Static Detection Based on Semantic Differencing”.
For consequential upgrades, check the project’s release notes and compatibility policy, then test the update in a suitable environment. Treat the version number as a useful first signal, not a substitute for checking changes that matter to your application.
What do prerelease and build labels mean?
SemVer can add identifiers after the three core numbers. They provide extra release information but do not change what MAJOR, MINOR, and PATCH represent.
- Prerelease identifier: A hyphen introduces it, as in
1.4.0-rc.1. A prerelease has lower precedence than the corresponding normal version, so1.4.0-rc.1comes before1.4.0. - Build metadata: A plus sign introduces it, as in
1.4.0+build.52. It does not affect version precedence.
The core numbers are compared numerically, not as text: 1.10.0 follows 1.9.0.
Recommended Free Tools
What changes before version 1.0.0?
Under the SemVer specification, a version such as 0.8.2 indicates that the public API is considered unstable; it may change at any time. Do not assume that pre-1.0 releases provide the same compatibility expectations as a stable public API. Check the project’s own policy and release notes before upgrading.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
