SemVer has failed us

A core problem is that the current system conflates two subtly different notions of version: the low-level package manager version (is it backwards compatible? will it build?) and the high-level person version (is this the same library with some changes, or is it a new generation or significant redesign?).

The first notion is needed for keeping our code stable but keeping up with bufixes and security patches. The second one is needed to deal with design issues: will this change require a lot of reworking? Will it change the underlying model or abstraction in the library?

Both of these are important. But because Semver requires bumping for any breaking changes—even if they are semantically minor—it can only address the first, low-level notion of versioning, not the second.

A possible solution? We can have two minor version numbers:

    4.1.0.2

Patches and backwards compatible changes work as always. But if you are making a breaking change, you have two options. If it's not too big, just increment the first one:

    4.2.0.0

But if you're really changing things up and creating a new generation of your library, go for

    5.0.0.0

Of course, the difference between the two major numbers is not well-specified. But that's fine! From the more technical, low-level perspective, it's no different from normal Semver: any change in the major version (either of the two numbers) can be breaking. It just also lets library authors send an additional signal to developers about the scope of the change.

For example, this scheme gives more information on how "stable" a library is. If the second major number is high, it means there are a lot of minor breaking changes; it would take a bit of active maintenance to keep up, but as long as the first major number is not changing, these steps won't be radical.

Personally, this approach makes a lot of sense to me. It's also more or less what Haskell packages use according to the "package versioning policy", and it seems to work pretty well. (There are some other pervasive issues with Haskell version numbers, but not related to how they treat major versions.)

For anyone in the Haskell world, it's obvious that semantic versioning[1] doesn't work. Some non-trivial amount of that is likely due to how horribly broken Cabal is, a problem the community remains in staunch denial of. But for the rest, one problem is that because Haskell more thoroughly specifies types, individual functions can remain the same in behavior but change in type because a bug-fix, say, fixes a record type used somewhere. The external interface might be largely the same, or even identical, but the binary output is non-backwards compatible. Dynamic libraries and strong, descriptive type systems aren't very compatible. The result is that a lot of bug fixes become minor version bumps.

These minor version bumps scare library developers, especially people that produce libraries that depend on libraries that depend on... and so on. So packages fail to build too often because of constraints. So the irony of this thorough process for package building is that humans have mucked it up and made it break builds. In almost every case in which semantic versions blocked some update from occurring and caused my work to stop, it was because I needed to bump the constraints on some third-party package. It's a boring process that I've only become too accustomed to:

1. try to build with updated libA 1.1.0-foobar

2. libB depended on libA 3. download source for libB

4. update constraint and repackage libB locally

5. rebuild main application

This happens just about every time there's a new version of any major piece of Haskell software.

If we really want to move into The Future, we need to start versioning individual modules or functions, instead of whole suites of software. But the cognitive burden of doing this is very high, and the software to do it hasn't been written yet.

[1] The Haskell community doesn't technically use semver, but rather a related policy called the package versioning policy. That's a nitpick though, and doesn't affect my argument.

Personally, I would far prefer a strong contracts system over semantic versioning. The ability to say "I rely on these N interfaces to present accept these argument types and return these types, and here are some test arguments and the values I expect returned" to be a much better way of describing what you rely on. Even better is that by defining things in terms of contracts, you should be able to replace dependencies with any module that matches the contract you require.

In general, it's always better to have a computer enforced standard over a human enforced one. Semantic versioning can just become human readable sugar over a set of contractual expectations.

The argument in the article seems strange to me: "downstream relied on undocumented behavior, and now that behavior has changed, so downstream breaks"

So what should upstream do? After all, the premise must be that the upstream does not control or even know about all the clients! The entire point is to separate the concerns, so how could upstream know if a bug fix is a breaking change if it passes the internal regression tests?

Of course they can't know without asking downstream, and hence the use of release candidates.