Semantic Versioning: MAJOR.MINOR.PATCH Rules Explained
November 11, 2026 · 11 min read
Semantic Versioning: How MAJOR.MINOR.PATCH Works
Semantic versioning (SemVer) is a numbering scheme where a version like 2.4.1 tells users what changed. You bump MAJOR for breaking changes, MINOR for backward-compatible features and PATCH for bug fixes. This guide covers the SemVer 2.0.0 rules people get wrong, then carries them into npm ranges and Git tags.
What Is Semantic Versioning and How Does It Work?
A version number has three non-negative integers separated by dots: MAJOR.MINOR.PATCH. The SemVer 2.0.0 specification defines what each one promises. The whole system rests on one requirement: you have to declare a public API, either in code or in documentation, so users know which changes count.
Once that API exists, the three numbers carry meaning:
- MAJOR goes up when you make an incompatible change to the public API.
- MINOR goes up when you add backward-compatible functionality, or mark something as deprecated.
- PATCH goes up when you ship a backward-compatible bug fix.
That's the core meaning of semantic versioning: the number that moved tells users how careful to be with the upgrade.
Three smaller rules trip people up. Lower numbers reset when a higher one moves, so 1.4.7 becomes 2.0.0, not 2.4.7. Numbers have no leading zeros, so 1.02.0 isn't valid. And each number grows as an integer, so the next MINOR after 1.9.0 is 1.10.0, never 2.0.0 just because you ran out of single digits.
The rule people break most is immutability. Once you've released a version, its contents must never change. If 1.3.0 shipped with a bug, you fix it in 1.3.1. You don't quietly rebuild and re-upload 1.3.0.
Which Number Do You Bump? A Decision Rule for Every Release
Before a release, ask two questions in order. Does anything in this release break code that uses the public API? If yes, it's a MAJOR bump, even if the release also contains features and fixes. If no, does it add anything to the public API or deprecate something? If yes, it's MINOR. Otherwise it's PATCH.
"Breaking" is wider than deleting a function. Renaming an option, changing a default, tightening input validation or changing a return type can all break callers. Internal refactors, performance work and dependency updates that leave the public API untouched don't count as breaking. For a dependency update, the SemVer FAQ says the reason decides: PATCH if you made it to fix a bug, MINOR if it adds functionality.
The demo below encodes that rule as a Mermaid flowchart plus a quick reference table. Change a label or add a branch for your own project's edge cases, then copy the Markdown into your docs or open it in the editor.
Semantic Versioning Examples: One Library's Release History
Rules make more sense on a real timeline. Here's the release history of a small, made-up string library called slugkit, with the reason for each bump.
0.1.0 first public release, API still moving
0.2.0 renamed the separator option (allowed while in 0.x)
0.2.1 fixed a crash on empty strings
1.0.0 API declared stable and documented in the README
1.1.0 added a locale option
1.1.1 fixed handling of the Turkish dotted i
1.2.0 deprecated the lower option (it still works)
2.0.0-rc.0 removed the lower option, first release candidate
2.0.0-rc.1 fixed a regression reported against rc.0
2.0.0 stable release of the breaking change
Notice a few things. The jump from 0.2.1 to 1.0.0 isn't triggered by a breaking change. It's a statement that the API is now stable. The deprecation at 1.2.0 is a MINOR bump, because the old option still works. Removal waits for 2.0.0, which resets MINOR and PATCH to zero.
The release candidates let early adopters test the breaking change without anyone on ^1.2.0 receiving it by accident. You'll see why in the npm section.
Some bumps that look harmless break the rules too. Each line below is a transition people actually ship, with the verdict:
1.1.9 -> 1.1.10 right: each number keeps counting past 9
1.4.7 -> 2.4.7 wrong: a MAJOR bump resets MINOR and PATCH, so 2.0.0
1.4.7 -> 1.5.1 wrong: a MINOR bump resets PATCH, so 1.5.0
1.4.7 -> 1.04.8 wrong: no leading zeros, so 1.4.8
2.0.0 -> 2.0.0 wrong: re-uploading changed code under a released number
The last one is the hardest to spot, because nothing in the number changes. Registries usually block it, but private artifact stores and download pages often don't.
Pre-Release Tags, Build Metadata and Version Precedence
A pre-release version adds a hyphen and dot-separated identifiers after the patch number: 2.0.0-alpha, 2.0.0-beta.3, 2.0.0-rc.1. Identifiers use only ASCII letters, digits and hyphens. Numeric identifiers can't have leading zeros, so alpha.01 is invalid.
Build metadata goes after a plus sign: 2.0.0+20261111 or 2.0.0-rc.1+sha.5114f85. It records how a build was made. It's ignored when comparing versions, so 2.0.0+a and 2.0.0+b have the same precedence.
Precedence is where most hand-written explanations slip. The spec's own ordering chain is:
1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta
< 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0
Four rules produce that order:
- A pre-release always sorts below its normal version, so
1.0.0-rc.1comes before1.0.0. - Identifiers made only of digits compare as numbers, so
beta.2comes beforebeta.11. - Identifiers with letters compare in ASCII order. Uppercase sorts before lowercase, so
1.0.0-RC.1lands below1.0.0-alpha. - When all earlier identifiers match, the longer set wins, so
alpha.1beatsalpha.
Rule 3 is the quiet one. Pick lowercase pre-release labels and stick with them. Mix RC with alpha and your release candidates sort before your alphas.
What Do 0.x Versions and 1.0.0 Mean?
Major version zero is for initial development. The spec says anything may change at any time in 0.y.z, and the public API shouldn't be considered stable. Its FAQ suggests starting at 0.1.0 and bumping MINOR for each release.
Version 1.0.0 defines the public API. From then on, every bump follows the three rules strictly. The spec's guidance on when to get there is blunt. If your software runs in production, people depend on its API, or you worry about backward compatibility, you should probably be at 1.0.0 already.
npm's own docs take a different starting point and recommend that new packages start at 1.0.0. Both are reasonable. We prefer 0.1.0 for anything experimental and a jump to 1.0.0 the week someone outside the team depends on it. Staying on 0.x for years just hides breaking changes behind a number that promises nothing.
npm Semantic Versioning: Caret and Tilde Ranges
npm applies semantic versioning on the consumer side through ranges in package.json. When you run npm install with a package name, npm saves the dependency with a caret prefix by default (the save-prefix setting is ^). The node-semver range rules decide what each prefix allows.
| Range | Means | Accepts | Rejects |
|---|---|---|---|
^1.2.3 | >=1.2.3 <2.0.0-0 | 1.2.4, 1.9.0 | 2.0.0 |
~1.2.3 | >=1.2.3 <1.3.0-0 | 1.2.9 | 1.3.0 |
^0.2.3 | >=0.2.3 <0.3.0-0 | 0.2.9 | 0.3.0 |
^0.0.3 | >=0.0.3 <0.0.4-0 | 0.0.3 only | 0.0.4 |
1.2.3 | exactly 1.2.3 | 1.2.3 | 1.2.4 |
The caret rule is "don't change the left-most non-zero number". That's why ^0.2.3 behaves like a tilde and ^0.0.3 pins a single version. In effect, npm's caret treats a MINOR bump on 0.x as breaking.
Ranges only decide what a fresh install may pick. Your package-lock.json records the exact versions that were installed, and npm ci reproduces them, so a teammate's build doesn't drift when a dependency publishes 1.9.1.
Pre-releases are opt-in. A plain range such as ^1.2.3 won't install 1.2.4-beta.1 or 2.0.0-rc.1. A range only matches a pre-release when the range itself names a pre-release on the same MAJOR.MINOR.PATCH. That's what kept slugkit users safe during the release candidates.
On the publishing side, npm version bumps package.json for you. Inside a Git repository it also creates a commit and a tag, and it stops if the working directory has uncommitted changes.
npm version premajor --preid=rc # 1.2.0 -> 2.0.0-rc.0
npm version prerelease # 2.0.0-rc.0 -> 2.0.0-rc.1
npm version major # 2.0.0-rc.1 -> 2.0.0
The last line surprises people: bumping major from a release candidate of 2.0.0 gives you 2.0.0, not 3.0.0. Likewise npm version patch on 1.2.0-5 just drops the suffix and gives 1.2.0.
Semantic Versioning in Git: Tags and the v Prefix
Git has no idea what a version is. You mark a release by tagging its commit, usually with a v before the number:
git tag -a v2.0.0 -m "Release 2.0.0"
git push origin v2.0.0
The -a flag makes an annotated tag with a tagger, date and message. The second command matters because git push doesn't send tags by default. The git tag documentation covers signed tags and the other options.
Is v2.0.0 a semantic version? No. The SemVer FAQ says v1.2.3 is a tag name and the semantic version is 1.2.3. The v is a convention, and npm version follows it, since its tag-version-prefix setting defaults to v.
Sorting is the trap. A plain git tag -l sorts alphabetically, so v1.10.0 lists before v1.2.0. Add --sort=v:refname for version order. Even then, Git puts v2.0.0-rc.1 after v2.0.0 unless you set versionsort.suffix to -rc, so don't trust Git's order for pre-releases.
git tag -l --sort=v:refname
git -c versionsort.suffix=-rc tag -l --sort=v:refname
Semantic Versioning Guidelines for Maintainers
These are the software versioning best practices we'd apply to any library with outside users:
- Never re-publish a version number. If a release is broken, ship a new PATCH and mark the bad one as broken in your notes.
- Deprecate before you remove. Ship at least one MINOR release that warns about the old API, then remove it in the next MAJOR.
- Write down the public API. Your README or Markdown docs site should say what's covered and which version is current.
- Record every release. Our changelog generator drafts a Keep a Changelog or GitHub release notes entry from commit or git log text you paste. You still choose the version number. Our changelog example shows a finished file in the Keep a Changelog format.
- Make commit messages machine-readable if you automate. Conventional Commits is the common format that tools map to version bumps. Our Conventional Commits cheat sheet shows which commit type triggers which bump.
One honest limitation: semantic versioning is a promise, not a guarantee. Nothing stops a maintainer from shipping a breaking change in a PATCH, so lockfiles and tests still matter. It also fits libraries far better than end-user apps, where "breaking the public API" often has no clear meaning. For a ready-made README or CHANGELOG skeleton, see our Markdown templates.
SemVer Questions From Release Day
Semantic versioning works when the numbers stay honest: declare the API, bump the right number, never touch a released version, and keep pre-releases out of normal ranges. Write down your rules in the README so contributors follow them too. You can draft that README, sketch your bump flowchart in Mermaid and preview both side by side in the editor, free and without an account.