About Semantic Versioning
This page is a reference for semantic versioning, the three-number convention that makes a version string communicate what changed: a major number for changes that break compatibility, a minor number for additions that remain backward compatible, and a patch number for fixes that change no behaviour anyone should depend on.
The value of the convention is that it turns a version into a promise. A dependency manager reads those three positions and decides whether an upgrade is safe to apply automatically, so the numbering is not cosmetic — it is the contract that automated updates rely on. The page sets out the three positions with the increment rule for each and works through examples of the same starting version being bumped in each of the three ways.
It is a reference rather than a calculator: there is nothing to enter and no version to compute. The interesting judgement in versioning is not arithmetic anyway, but deciding whether a change is breaking. Removing an export, tightening validation or renaming a parameter are breaking; adding an optional argument is not. Pre-release identifiers and build metadata are also part of the specification, and are worth reading up on separately if you publish to a registry that uses them.
Nothing on the page responds to your input, so it cannot help with the parts of versioning that are actually mechanical. There is no field in which to enter a current version and a change type and get the next version back, no comparison of two versions to determine which is higher, and no range checker that would tell you whether one version satisfies a constraint such as a caret or tilde range. Pre-release ordering and build metadata are mentioned but not resolved, so the subtler rules about how a pre-release sorts against its own release are not worked through here. Treat the page as the rulebook you consult while deciding what to publish.
How to use Semantic Versioning
- 1 Read the three positions to remind yourself which increment means what.
- 2 Match your change against the increment rules before you publish.
- 3 Use the worked examples to check that you have classified the change the way a consumer of your package would.
Frequently asked questions
Is a change to behaviour with no signature change a major version?
Usually yes. If callers could reasonably have depended on the old behaviour, changing it breaks them even though nothing failed to compile. The convention protects expectations, not just interfaces, which is why bug fixes that alter long-standing behaviour are often shipped as a major version.
When should the major number go up on a version below 1.0?
While the version is still zero, the convention treats everything as potentially unstable, so the minor number carries the breaking changes and the patch number the rest. It is a widely used reading rather than a strict requirement, and it is why many maintainers stay on a zero major version deliberately.
What is the difference between a pre-release version and a build number?
A pre-release identifier sorts before the release it precedes, so it is chosen by a resolver only when explicitly allowed; build metadata is ignored entirely when comparing versions. Treating the two as interchangeable is a common source of resolution surprises.
Does a version number guarantee the package works?
No, and it never did. Semantic versioning is a communication convention that depends on the maintainer following it. An incorrect increment is a documentation bug that your dependency manager will act on without knowing any better.
Free, online, and private
Free to use
Semantic Versioning is completely free. There is no account to create, no login, and no hidden charge or usage limit.
Runs online in your browser
It is a free online tool that runs entirely in your browser. Nothing to download or install — open the page and start using it right away.
Your data stays private
All processing happens locally on your device. Your input is never uploaded, stored, or tracked, so it never leaves your browser.
How Semantic Versioning behaves in detail
These are the specifics of this implementation — the exact ranges, defaults and fixed settings you are working with.
| Parameter | Value |
|---|---|
| Page type | a static reference — one fixed string is returned and no input is read |
| Content | the three parts MAJOR.MINOR.PATCH with what each signals: breaking, features, bug fixes |
| Worked examples | 1.4.2 to 2.0.0 (breaking), 1.4.2 to 1.5.0 (new feature), 1.4.2 to 1.4.3 (bug fix) |
| Update mode | declared with live: false, so the text is produced on submit rather than recomputed on each keystroke |
Compiled from the implementation of this tool and checked against it by itoolnet.
What Semantic Versioning does not do
Knowing the edges of a tool saves more time than another list of its features. These are the cases where it will not do what you might expect.
- There is no input of any kind, so nothing can be compared or validated: you cannot paste two versions such as 1.2.3 and 1.10.0 and have their order resolved, and a malformed version string cannot be checked either.
- Pre-release and build metadata are absent from the whole page. Nothing covers 1.0.0-beta.1, the +build suffix, or the precedence rules that decide whether a pre-release sorts before the release it belongs to.
- The text only defines what each of the three numbers means. It never mentions the 0.y.z convention where anything may change, and gives no guidance on which number to bump for a dependency update or a docs-only change.
Tested and documented by itoolnet, the team that builds and maintains this site.