Nate Meyvis

Against SemVer

Semantic versioning is the most standard way of naming versions of software. Here is the spec, but in short, you define a contract and then give every version a name like 1.7.2, where 1 is the "major version," 7 is the "minor version," and 2 is the "patch." The rules are:

  1. Increment the major version when there's a breaking change to the contract (except in version 0, when "anything can change at any time").
  2. Increment the minor version when you add functionality without breaking anything.
  3. Increment the patch number when you fix something without changing any functionality.

There is an extended argument against semantic versioning in Software Engineering at Google. The argument there is extremely lucid, so you can just go read it, but here are some essential points:

  1. Consumers rarely use every part of a contract, so semantic versioning often over-predicts the likelihood that a change will break a caller.
  2. Consumers often rely on aspects of an API not captured in the contract, so semantic versioning often under-predicts the likelihood that a change will break a caller.
  3. Many aspects of APIs--e.g., small changes to performance characteristics--aren't readily captured by contracts.
  4. People make mistakes in classifying changes as breaking or non-breaking.

This argument is both convincing and, in my experience, empirically justified. When a dependency upgrade breaks code I'm responsible for, semantic versioning conventions almost never help me prevent or remediate the breakage. Put another way: relative to a baseline of a system where releases are tagged as "very different" or "a little different," I don't think the SemVer scheme has helped my teams.

I'd add two more, less polite, observations:

  1. Even SemVer advocates often ignore the special meaning of the 0 major version. I have been told, with grave seriousness, that a project is "very serious about SemVer," and then seen that the project (i) is advertised as stable, (ii) will not break certain functionality, but (iii) is still on a 0.Y.Z release.
  2. Many people claim to be serious about semantic versioning but do not have a published contract against which to evaluate changes as breaking or non-breaking. The very notion of a breaking change is relative to an API. If the API doesn't exist, the notion is not well-defined. If it exists but only in someone's mind, from the consumer's perspective it might as well not exist.

I don't think my experience is in this respect extraordinary. And I've never heard or read an argument against the Software Engineering at Google claims about semantic versioning1. Yet SemVer remains a "Smart Person Recommendation" in software. Your superiors are likely to say it's very important. If they are reviewing a project plan, they are likely to tell you to use semantic versioning. (Amusingly, they're probably more likely to insist on semantic versioning than they are to insist on there being a well-specified API contract!)

Let's provisionally define these "Smart Person Recommendations" as things that are not completely obvious but are often endorsed, and almost never argued against, by influential people in software teams. Many of these are indeed good ideas. (Many people don't find it obvious that we should have accurate documentation or thorough automated testing, and we should be grateful that influential people endorse these.) But some are mere fashions, or at least not much better than relevant alternatives. As far as I can tell, SemVer is one of the latter.

  1. Except for ones I've asked LLMs to produce for me.↩

#potofhoney #software #the sociology of software