Ode to Semantic Versioning

If you author a library or module, whether it’s publicly available or a cog hidden inside a bigger product, you should seriously consider using Semantic Versioning.

There are a lot of versioning schemes with rich traditions, like Sentimental Versioning or Marketing Versioning — better known as “We’ll increase the major version whenever we want you to pay again” — but they all miss the key point: Versioning is not about how the author feels about the release, it’s about helping users.

Dependencies of any project are generally recorded as little more than a list of names and versions. The brilliance of Semantic Versioning (or SemVer for short) lies in its ability to emboss critical information on this tiny, tiny surface. It is specifically designed to turn a previously useless identifier (“Bigger is better, right?”) into a valuable asset.

You can go and read the full specification, but here’s the key part: Increase the major version of your library every time you introduce changes that might break something your users do. For every single release that might break anything!

Well-behaved jelly

Let’s say you’ve just discovered that version 5.3.0 of jelly-sandwich finally added the peanut-butter support you've been waiting for. Quickly, fetch that release and start crafting delicious code!

If jelly-sandwich follows Semantic Versioning, a single glance at your dependency declaration answers the most important question: Do you need to change something when you update?

  • Already using a 5.x.x version? Then you're good to go! No need to look anywhere else.
  • Still relying on the old 3.x.x release? Then you know exactly where to search for breaking changes: The release notes of jelly-sandwich#4.0.0 and 5.0.0. Easy. You can ignore all other versions that may have been published.

Sure, adapting to those breaking changes may require substantial effort — but that is jelly-sandwich's fault, not SemVer's. And hey, it's for peanut-butter!

Libraries craving for romance?

But if that precious library is still in love with Sentimental Versioning, Romantic Versioning or even Random Versioning? You are completely out of luck. You have to find and read the release notes of every single version in-between yours and 5.3.0 to check for breaking changes that might affect you.

Yes, even those cute little minor-dash-rc1 updates that fixed a small issue with leaking jam because — oops—now you need to use a separate plate for each sandwich!

As a library author, using SemVer means respecting your users’ time and resources. This bears repeating: If you publish a library that follows Semantic Versioning you are saving each and every user time and effort. You help them preserve their precious cognitive resources. You might make them less anxious about updating to the latest version. This means more people can use all those awesome features that you worked so hard to implement. Hooray!


Of course, following SemVer is not trivial. It requires you to think carefully about every change you publish and it does not protect you from breaking something by accident — but it gives you a way to fix that.

If your environment uses shared transitive dependencies — like Java, Bower and pretty much everything except npm — you have to be even more careful. But don’t worry, we’ll cover those details another time…

Do you agree? Disagree? Have trouble follwing SemVer? Let me know via Email or Twitter.

Originally published at blog.leanbyte.com on September 21, 2015.