Why semantic versioning is not going to solve all our problems

September 3, 2016

One of the things going around the programming community these days is Semantic Versioning, generally shortened to 'semver'. Semver proponents generally claim that faithfully following the semver dogma will solve all our version to version compatibility surprises and woes, or at least let us know about breaking changes in things. The sysadmins in the audience are probably laughing hollowly at this point, and we are completely correct to do so.

Recently I read Why Node Sass broke your code and SemVer (via), in which the team behind Node Sass wrote a careful article to explain why a bunch of people wound up with suddenly non-working projects after applying what semver claimed was a minor version where 'you add[ed] functionality in a backwards-compatible manner'. In fact, say the Node Sass people, this is a correctly semver-versioned change, despite breaking your code.

(You can read the article for the details. I take no position here.)

What it comes down to is that people's understanding of semver and related versioning issues is ultimately a social one. Versioning things is a social act, and as a social act different people can have different understandings of what it means and what it requires. The Node Sass case clearly shows a gap in understanding. Everyone thought they understood what was meant by 'semver', but the Node Sass people turned out to have one understanding and a bunch of other people had another one. Eventually the Node Sass people made a change that was minor under their understanding and major under other people's, and drama appears to have ensued.

This is not a problem that you can solve easily, or really at all. Except in extremely limited situations, versioning is not something that can be handled and tested mechanically; human beings are always going to be involved, and that means they are injecting their messy 'judgement' into these decisions. When people use their judgement, they are relying on their understanding of what is going on and what is the proper thing to do, and that's ultimately a social issue. Creating comprehensive, complete shared understandings is what can be politely called a pretty hard social problem.

Looked at from one perspective, the entire job of technical specifications like POSIX is to create a shared social understanding of what 'Unix' or 'TCP' or 'C' or whatever is. And despite all of the work and exacting detail that has been poured into all of those standards, people still wind up disagreeing over what they mean (in the form of what they permit or forbid). The typical attempt to create shared understandings involves an order of magnitude more informality (and less work) than such standards, so it should be no surprise that there are periodic disagreements such as this.


Comments on this page:

By dozzie at 2016-09-03 08:59:31:

In other words, it was a case of "it's not a feature, it's a bug!"

By Jonathan at 2016-09-08 13:53:15:

The linked article fails to address why they didn't bump a mid-version number rather than minor for the behaviour breaking change. The Linux kernel approach towards api is sensible here.

Written on 03 September 2016.
« Some thoughts on Python 3 module APIs and Unicode conversion errors
What I want in Vim with the mouse (and why I don't think I can have it) »

Page tools: View Source, View Normal, Add Comment.
Search:
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Sat Sep 3 00:52:46 2016
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.