Skip to main content Accessibility Feedback

Semantic versioning

In programming, a very popular way of versioning is code is semantic versioning, sometimes called semver.

It’s a powerful way to communicate what’s new about a code update through version number alone. But, it can be confusing, in large part because many developers use it incorrectly.

Let’s quickly breakdown how semantic versioning works.


Semantic versioning uses a major.minor.patch pattern.

If a piece code was version 4.2.1, 4 would be the major version, 2 would be the minor version, and 1 would be the patch.

The semantic versioning website defines them like this:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards compatible manner, and
  3. PATCH version when you make backwards compatible bug fixes.

That works, but I tend to mentally think of them a bit differently.


This is literally the same thing as the real definitions above, but it’s how I wrap my brain around semantic versioning.

  1. A major version bump breaks the existing code base’s backwards compatibility.
  2. A minor version bump adds one or more new features.
  3. A patch version bump fixes bugs or security issues.

Pick the highest version type that applies

Let’s say the current version of your code base is 4.2.1.

You push a release that adds new features but also breaks backwards compatibility. What’s the new version number?

With semantic versioning, it should be 5.0.0, because it’s a breaking change. Yes, it adds new features, but you only increase the highest version type.

From a strategic perspective, if you’re implementing bug fixes but also want to implement some breaking changes, it might make sense to issue two releases.

  1. Release a patch bug fix update first…
  2. Then add breaking changes and release a major version bump.

I personally think it’s ok to tie new features to a breaking major version bump, though.