The SemVer Talk 1.0

Everyone deals with version numbers… and not just for code. Which version of jQuery are you using? Which PSD is the final design? Should you upgrade your mobile phone’s OS?

When it comes to production systems, meaningless version numbers are not just annoying – they can be destructive. Package management systems like NPM expect published modules to follow Semantic Versioning. When these rules are broken, chances are your project will be broken too.

So what ARE the rules? Can they rescue your designs from new-website-final_final2_revised.psd hell? What should you do with your code and what should you expect from others? How can you minimise risk without spending your entire day reading release notes?

It’s time to learn the ways of SemVer.

Modern web development faces a challenge in the number and range of dependencies that need to be managed, and the notation of their versions – which few people really understand.

Versioning is often an arbitrary affair involving the assignation of random numbers and names.

There are many versioning schemes, most of which are sequential or based on date of release (which is also sequential), degree of change, degree of compatibility or random strings.

Semantic Versioning aims to communicate a lot of information in a very short string. It’s a code, a compression.

SemVer uses three numbers. The first one records the major version, the second records the minor version, and the third one talks about patches. Each is relative to its previous versions.

Using SemVer is part of adopting a professional approach to web development, displaying the kind of rigour that warrants a job title like Engineer.

Semantic refers to meaning, so Semantic Versioning effectively means notating changes in a meaningful way.

SemVer is the most popular versioning control system among web developers, and it is also used by default by people using Node, Python, Java.

Patches and bug fixes are reset when a new minor version is released. Version 1.0 is released, a bug is found and fixed to make it Version 1.0.1, then a feature is added to make it Version 1.1 – the bug fix applied to 1.0 is subsumed into the new minor version.  

New versions in which code changes are not backwards-compatible – previous versions no longer work – are called breaking changes and bring a new major version number.

Use deprecation to indicate when something is still available but will soon be unavailable. This gives the developer freedom to move on and users time to update.

A simple cheat sheet for SemVer is 1.2.3 – 1 = broken, 2 = improved, 3 = fixed.

SemVer is not based on the size, or the number, or the count of changes, and it’s not trying to guess if your code works, or how much work is required to upgrade. It’s just saying, “I’ve changed.”

Versioning notation is not a single number. Each part is separate and relates to the previous version only. Version 1.9 is not necessarily followed by 2.0. It can be, if the next version is new major version, but it could also go to 1.10 for a new minor version, or it could be 1.9.1 for a new patched version.

Since SemVer is just a logical way of recording change, it works for anything that requires filenaming to track version changes, including design files and text content files.

Not everyone follows or agrees with SemVer. To protect yourself, lock noncompliant dependencies and don’t let them upgrade – or don’t use them at all.

There are people who believe that bumping version numbers will make users think an API is unstable. The Germans have a word for this: Haupversionsnummernerhöhungsangst – fear of increasing the major version number. This fear should be overcome.