#software versioning

SemVer, but you never have more than one API change per version bump. No compromises, no mercy. Even if that means you go from version 1.9.6 to 6.0.0 in one day because you didn't release for a while, and then to 6.2.4 the next day because you did some simple features and quick fixes.

This is how a machine with smooth release automation, good testing, and no feelings projected onto version numbers would do things. Simple, elegant, powerful - beautiful.

Every release becomes a discrete atom of functionality change - if two things change at once it's because they were so intimately connected that splitting any further would make for a broken or useless release. The structure of changelogs becomes simpler, and more trivial to parse and display in various ways. Users, developers, and automated tooling can isolate upgrade-caused breakages down to specific changes in one or more dependencies, then use the version of that release to easily communicate about exactly that change.

In principle, manually deciding your next SemVer numbers, or even telling some tool "give me the next {bugfix,feature,breaking} change's version" is backwards. You know what your interface is, you already encode that in a way that communicates it to both machines and humans - in the docs, in the tests, and in the implementation - and you have releases and commits which remember this from previous versions.

If we know what the interface is, we can always look at the current variant of a thing, compare it to the last variant of that thing with a SemVer version, and deduce what the SemVer bump should be. The challenge is knowing what the interface is precisely enough, and then saying that to our tools through work that we ought to be doing anyway, like writing good tests and documentation.

One problem people run into with SemVer is trying to use it for things that aren't releases.

They'll decide "this project will use SemVer" as if it is a complete answer to versioning, and then when they come to the question of how to fill the version string for automated tests and continuous integration, they try to shove the square peg of SemVer into that round hole use-case.

Last I checked there was a GitHub issue with hundreds of people weighing in and no end in sight. SemVer is not designed to provide that answer. It's designed to refer to just the snapshots of code that you decided to release. It's not designed for all the stuff in the middle, before you're ready to decide and say what the next increment of API change is.

So we could reasonably say that the "correct" answer to "I'm doing SemVer, what should I set the version to for this non-release build?" is: something that does not even parse as a valid SemVer version.

I think SemVer is great. I have a few issues with it, but over all, it is a beautiful idea.

However, it has become overwhelmingly clear to me that most people, teams, and organizations simply don't have what it takes to use SemVer. Because it takes a neurotic intrinsic motivation to exactingly learn its rules to the letter, and to then feel that they are more important than all realistic competing priorities.

If I was being diligent about making the code in every commit "proactively honest" with the version numbering it contains, for projects where the version number lives in the source code rather than getting injected during the build, then:

Right after cutting a release, before committing anything else - unless I already knew that the next commit would be a finished release on its own - I would always make the very next commit contain just an update to the version string to a distinctly "pre-release" or "development" version number.

Later, once I am ready to cut the next release, after I have committed all the other changes that are going into the next release, I would make one final commit with just the change of the version string to the proper release version. That's the commit that would get tagged with the release number.

Repeat.

Hyrum's Law has one "fun" ramification for SemVer: if you

intended your code to behave a certain way, and

you promised that behavior in your API documentation, but then

you discover that your released code has always behaved differently due to a bug, well then

surprise! For SemVer purposes, this might now be a documentation bug, not a behavior bug.

Unless you know your users have been writing code that relies on the documented behavior, assume that production use relies on the actual behavior.

Release a documentation "fix", changing the documentation to match the actual broken unintended behavior. If your documentation falls under SemVer, bump the patch SemVer number, otherwise bump whatever sub-SemVer stuff you have going on.