Skip to content
Velloreth
Programming 8 min read

Semantic Versioning Explained: MAJOR.MINOR.PATCH

What MAJOR.MINOR.PATCH actually promises, when a breaking change has to bump the major version, and why caret and tilde ranges behave the way they do.

By

What semantic versioning actually is

Semantic versioning is a convention for numbering software releases as three integers separated by dots: MAJOR.MINOR.PATCH, written 1.4.2. Each integer is a promise about what changing it means for anyone already using your code.

  • MAJOR increments when you make incompatible API changes.
  • MINOR increments when you add functionality in a backward-compatible way.
  • PATCH increments when you make backward-compatible bug fixes.

The specification lives at semver.org and is short enough to read in full. What the spec does not say is just as important as what it does: the version number is not a measure of effort, of quality, or of marketing importance. 2.0.0 is not “twice as good” as 1.0.0. It means “callers of 1.x may break.”

That is the entire idea, and almost every practical problem with versions comes from someone treating the number as a progress bar instead of a contract.

Why the contract exists at all

Modern projects depend on dozens or hundreds of packages, and those packages depend on others. Nobody reviews every transitive dependency by hand on every update. Instead, the tooling automates the decision:

“Give me the newest version that still satisfies my range, and trust that the publisher marked anything incompatible with a major bump.”

This only works if publishers honour the promise. When a maintainer ships a breaking change in a patch release, every downstream project that trusted the range gets a broken build with no signal in advance — an incident caused by a version number rather than by code.

The failure mode is asymmetric. Honouring semver costs a maintainer one extra major version number. Breaking it costs thousands of downstream developers an afternoon each.

The decision tree for picking a number

This is the part people get wrong, so here is the decision in order.

Start at MAJOR. Would any existing caller break? Not “might a caller be surprised” — would correct code that worked before now fail, or silently do something different?

Things that are always MAJOR:

  • Removing or renaming a public function, class, endpoint, or field.
  • Changing the type or meaning of an existing parameter.
  • Changing a default value that alters behaviour.
  • Tightening validation so input that used to be accepted is now rejected.
  • Bumping the minimum runtime, language, or platform version.
  • Changing an output format: a response shape, a serialized structure, an error message that callers parse.
  • Fixing a “bug” that users depend on. This one hurts, but if documented behaviour changes, callers must be warned.

If none of those apply, check MINOR. Are you adding something? A new optional parameter, a new endpoint, a new exported function, a new config key with an existing default — anything purely additive is MINOR.

Otherwise, it is PATCH: bug fixes that restore intended behaviour without changing the documented contract, plus performance and internal refactors.

Two rules that resolve most arguments:

Rule one: a breaking change is a major bump even if it is one line. Size is irrelevant. Scope of impact is what the number encodes.

Rule two: internal changes are not releases at all unless they change something observable. Refactoring a private function is a commit, not necessarily a version.

Pre-release versions and build metadata

The spec allows suffixes with clear precedence rules.

1.0.0-alpha.1 → 1.0.0-beta.1 → 1.0.0-rc.1 → 1.0.0 is the standard progression, where alpha is early, beta is feature-complete, and rc (release candidate) means “unless something breaks, this ships.”

Pre-release versions have lower precedence than the corresponding release, and package managers exclude them from normal ranges by default. ^1.0.0 will not install 1.1.0-beta.1. You have to ask for a pre-release explicitly, either with a range that includes it or with an exact version.

Build metadata like 1.0.0+build.451 is allowed but ignored for precedence — 1.0.0+abc and 1.0.0+xyz are the same version as far as resolution is concerned. It is useful for traceability and useless for pinning.

Caret and tilde, precisely

This is where most day-to-day confusion lives, and the two operators are easier to remember once you see what each one is protecting.

RangeAcceptsProtects against
^1.2.3>=1.2.3 <2.0.0major bumps only
~1.2.3>=1.2.3 <1.3.0minor and major bumps
1.2.3exactly 1.2.3everything
1.2.x>=1.2.0 <1.3.0same as tilde
>=1.2.3 <2explicit rangeexactly what you wrote

The caret says “give me the newest compatible version” and trusts that minor releases are safe — which is the semver promise. The tilde says “give me patches only” and is the right choice when you trust patch fixes but not new features.

There is one important special case. Below 1.0.0, the caret behaves more conservatively, because the spec declares 0.x unstable:

  • ^0.2.3 accepts >=0.2.3 <0.3.0 — minor bumps are treated as breaking.
  • ^0.0.3 accepts only 0.0.3 — no range at all.

This trips people up constantly. A brand-new package at 0.4.1 will not auto-upgrade to 0.5.0 under a caret, and that is intentional, not a bug.

Ranges do not give you reproducible builds — lockfiles do

A package.json range is a query. A lockfile is an answer.

"foo": "^1.2.3" says “some version in this range would be acceptable.” The lockfile records that on this machine, on this date, it resolved to 1.4.7 and here is the hash of the tarball. Without committing the lockfile, two developers installing the same package.json can get different trees, and CI can build something different from what you tested.

The practical rules that follow:

  • Commit the lockfile for applications, always.
  • Run npm ci, not npm install, in CI — ci installs exactly the lockfile and fails if it disagrees with package.json.
  • Update deliberately. npm update inside a caret range is usually safe; crossing a major is not, and should be a reviewed change with a changelog read.

If your build works on one machine and not another, the lockfile is one of the first things to check. Debugging strategies that work walks through that class of “works on my machine” investigation, and reproducible development environments with dotfiles covers the toolchain side of the same problem.

Versioning things that are not libraries

Application version numbers have no downstream callers, so the compatibility promise is internal — but it is still worth being consistent, because deployment tooling, changelogs, and rollbacks all key off it.

A convenient and widely used mapping for a web application:

  • PATCH — a bug fix deploy, no schema or API change.
  • MINOR — new user-facing features, backward-compatible API additions.
  • MAJOR — an API breaking change or a data migration that cannot be rolled back.

If you are shipping continuously and every deploy is a patch, consider whether the number is telling anyone anything. A version number that increments on every commit for no reason is a build number wearing a semver costume.

Common false beliefs, corrected

“A new feature means a minor bump.” Only if it is backward-compatible. A new required parameter is a major change.

“We can call it 2.0 for marketing.” You can, but then every downstream range breaks at once. If the release is not actually incompatible, use a minor bump and put the marketing number in the announcement.

“Fixing a bug is always a patch.” Only if documented behaviour is unchanged. If your code returned null on error and you change it to throw, that is a major change no matter how correct the new behaviour is.

“Our API is versioned in the URL, so semver does not apply.” You have two version numbers now. They should agree, or you should document which one is authoritative.

“Semver is enforced by tooling.” It is not. Nothing stops a maintainer shipping a breaking patch. The only defence is reading changelogs before widening ranges, and pinning dependencies that have burned you.

How to actually apply this on a project

  1. Write the compatibility contract down. One paragraph: what counts as public, what counts as internal. Most semver disputes are really disputes about what was ever promised.
  2. Automate version bumping from commit messages. Conventional Commits maps directly onto semver — fix: → patch, feat: → minor, BREAKING CHANGE: → major — and tools can compute the next version from git history instead of from memory.
  3. Generate the changelog from the same commits, so the release notes and the number can never disagree.
  4. Tag every release in git with the same string as the package version, so the number resolves back to a commit.
  5. Announce majors loudly, with a migration section. A major bump nobody notices is a major bump that breaks people quietly.

Step 2 and 3 are the ones that pay off immediately. If you are already scripting your release process, automating boring work with shell scripts covers the patterns for wiring this into a repeatable command, and task runners compared is worth reading before you hand-roll the glue.

Why the convention is worth keeping

Semantic versioning is a small piece of social infrastructure. It costs a maintainer a decision at release time and saves an entire ecosystem from reading every diff. When it is honoured, dependency updates become a routine command. When it is ignored, “update your dependencies” becomes an act of faith.

The version number is not a label on the box. It is the box’s contents list, written for someone who will never open it.

Frequently asked questions

What does 1.4.2 mean in semantic versioning?
1 is the major version, meaning the fourth incompatible release line. 4 is the minor version, meaning backward-compatible features were added. 2 is the patch version, meaning backward-compatible bug fixes only.
Should I use caret or tilde in package.json?
Use the caret for libraries you trust to follow semver, which is the default npm writes. Use the tilde or an exact pin when a dependency is known to break on minor releases, or in applications where you want deliberate control over upgrades.
When should I bump the major version to 2.0.0?
When a change would break an existing correct caller: removing or renaming a public function, changing a parameter's meaning, changing a default, tightening validation, or requiring a newer runtime. Anything that makes existing code fail is a major bump.
Is semantic versioning legally required?
No. Semver is a convention with no enforcement. It works only because package managers and downstream developers trust publishers to follow it, which is exactly why breaking the promise causes disproportionate damage.
What does a pre-release suffix like 1.0.0-beta.1 mean?
It marks a version as having lower precedence than 1.0.0 itself and is normally excluded from version ranges unless you explicitly opt in. Package managers will not install a beta to satisfy ^1.0.0.