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
If a piece code was version
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:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards compatible manner, and
- 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.
- A major version bump breaks the existing code base’s backwards compatibility.
- A minor version bump adds one or more new features.
- 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
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.
- Release a patch bug fix update first…
- 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.