DX Heroes logo

Back to insights

#engineering
#versioning

What is Semantic Versioning (SemVer)?

Length: 

4 min

Published: 

June 9, 2026

What is Semantic Versioning (SemVer)?

What is Semantic Versioning (SemVer)?

Semantic Versioning, usually shortened to SemVer, is a convention for numbering software releases. Each version has three numbers separated by dots in the format MAJOR.MINOR.PATCH, for example 2.4.1. Each number carries a meaning:

  • MAJOR goes up when you make a change that breaks compatibility, so existing code that uses the software may stop working.
  • MINOR goes up when you add new features that keep backward compatibility, so nothing that already worked breaks.
  • PATCH goes up when you fix a bug without changing any behavior people rely on.

The rules are defined in a short public specification at semver.org. Package managers like npm, pip, and Cargo all build on them.

In plain words

Think of a version number as a label on a product. The PATCH number is a quiet repair: same product, one defect fixed. The MINOR number is a new feature added to the box: everything you used before still works, you just get more. The MAJOR number is a redesign: the new model may not fit your old setup, so read the manual before you switch.

How to apply it

When you publish a new release, you decide which number to raise based on what changed since the last version. You only ever increase one of the three, and the numbers to its right reset to zero.

  • Bump PATCH (1.4.2 to 1.4.3) for bug fixes and internal tweaks that nobody using the software will notice, except that something broken now works.
  • Bump MINOR (1.4.3 to 1.5.0) when you add functionality that is backward compatible. Old code keeps running, new code can use the new features.
  • Bump MAJOR (1.5.0 to 2.0.0) when you change or remove something that existing users depend on. Anything that forces them to rewrite their code is a breaking change.

Two more conventions are worth knowing. Version 0.x.y signals early development, where anything can change and the usual guarantees do not apply yet. A suffix like 1.0.0-beta.1 marks a pre-release that is not yet considered stable.

On the consumer side, you also use SemVer when you declare which versions of a dependency you accept. A range like ^1.4.0 means "any 1.x version from 1.4.0 up, but not 2.0.0", which lets you pull in safe updates while blocking breaking ones.

Common pitfalls

  • Treating every release as MAJOR. Some teams bump the first number for marketing reasons. That throws away the signal: under SemVer, 2.0.0 is a promise that something broke, not that the release is exciting.
  • Hiding a breaking change in a MINOR or PATCH. This is the most damaging mistake. A user who allows automatic patch updates trusts that nothing will break. One renamed function in a "patch" can take down their build.
  • Forgetting that the public API defines compatibility. A change only breaks compatibility if it affects what you have promised others can use. Refactoring private internals is a PATCH, even if the rewrite was large.
  • Ignoring 0.x rules. While a project is at 0.x.y, a MINOR bump can break things. Do not assume the same safety you would expect after 1.0.0.

Related articles:

Back to insights

Want to stay one step ahead?

Don't miss our best insights. No spam, just practical analyses, invitations to exclusive events, and podcast summaries delivered straight to your inbox.