Semantic version (SemVer) is possibly the most widely used software versioning scheme.
We all know how SemVer works: MAJOR.MINOR.PATCH. The first number is for backward-incompatible changes, the middle number is for backward-compatible new features, and the last number is for backward-compatible bugfixes.
…it’s a shame how infrequently it actually seems to be used this way!
Backward incompatible changes on minor versions happen all the time. By far the most common example are deprecations, even amongst libraries that claim to follow SemVer. Meanwhile, major version bumps often correspond to something big-and-shiny happening. The major version is used for ✨marketing✨.
If you’ve been around software for long enough then I reckon the chances are good that you’ve seen many libraries use this approach already. 1 And to be clear, this isn’t a post complaining about a misuse of SemVer. Rather: I am writing this post because I think it might be worth acknowledging this popular reality, and giving it a name!
That reality – ‘RealSemVer’
It works like so:
MAJOR.MINOR.PATCH
Major version bumps may include backward-incompatible changes, and are typically used for advertising substantial (exciting!) changes to the library.
Minor version bumps may include backward-incompatible changes, and are typically used for new features or deprecations.
Patch version bumps must only include backward-compatible changes, and are typically used for bugfixes.
There is no special meaning assigned to MAJOR or MINOR versions 0. 2
The definition of ‘backward (in)compatible’ is for each project to decide. For example breaking changes to private/undocumented/experimental APIs, or bugfixes that induce changes in behaviour, or breaking changes to the ABI, may all be considered ‘backward compatible’. 3
That’s it. 4 Much like SemVer before it:
This is not a new or revolutionary idea. In fact, you probably do something close to this already.
Should you use this?
For now I’m just some guy with a blog and an observation (and quite a lot of open-source software too).
But I think I might intentionally start using this for my software libraries. It seems to me that having a ‘marketing number’ is genuinely useful. There’s a reason so many library authors already use this, even if it’s not by this name. 5
At the very least now that I’ve written this post, I have a resource to point my coworkers to every time a library makes a breaking change in their minor version release, again! (‘Ah you see, this is a library that is actually following RealSemVer.’) Indeed whilst I’ve been mulling this idea over for a while, I was inspired to write this post by a certain release from a certain library, which brought a lot of stress to these aforementioned coworkers, and which to protect the guilty shall not be named.