#semver

[mentalisttraceur-software]

Relentless SemVer

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.

We should start looking at doing SemVer like that. This is the right direction. The future is fairly simple computer algorithms trying and testing software upgrades, calling in the conscious minds only when they've detected and then isolated the failure.

[blubberquark]

Actually Useful SemVer

By itself, i.e. if you merely follow the specification, SemVer is quite useless. SemVer as it is practised is even more useless. Developers often break compatibility when they think they have a good enough reason, instead of incrementing the major version number, or they decide to increment the major version number with every release.

SemVer only becomes useful when done properly (according to the specification), while also following the spirit of SemVer.

The first thing that is missing from many projects that nominally implement semantic versioning is the specification of a public API. This is already part of the official SemVer spec, but people are not taking it seriously enough. Often it is not clear which parts of the API are public, and the API is under-specified. It can’t just be function signatures and types. If a function expects certain contracts to be upheld by the caller, that should be part of the API specification. If there is unspecified or undefined behaviour, this should be part of the official public API, otherwise pretty much any change to the implementation in a minor release could break existing code. All exceptions that might be thrown (even in future releases), error return codes that the caller must check, preconditions that must hold, or implementation details that are not guaranteed to stay this way (for example the ordered-ness of returned lists) have to be specified.

If you don‘t, people will complain that you changed the public API when you just fix a bug. It’s probably a good idea to make a policy about fixing bugs. Do you preserve bug-for-bug compatibility with the last release, or do you restore the behaviour promised by the spec?

Backward-compatible minor releases are useless if you increase the major version with every release. The whole point of SemVer is that minor releases are safe to upgrade to. An official roadmap or release schedule can tell downstream users what to expect from your project. Not every release is an LTS release, and not every bug fix will get backported, and maybe some major versions have no minor versions declared LTS releases at all. Still, if you don‘t release minor versions at all, or if you don‘t communicate when a new major version is around the corner, backward compatibility of minor versions is not all that useful.

In the same vein, your project should consider having release notes, changelogs, and migration guides. Even better than a compatible API for dependency resolution is an easy path to using the new API. Release notes can also point out changes in implementation or actual behaviour that are still conformant to the specified API.

Everything depends in one way or another on the CPU architecture, compiler version, and operating system. Platform support does not necessarily play nice with SemVer. Downstream users sometimes complain about dependencies that used to work no longer working, just because they switched from 32-bit OSX 10.5 on i386 to ARM64 mac OS 11.0. Unfortunately, there is not much you can do when Apple decides to stop shipping a sensible libGL. This is not conveyed by a version number, so you should probably mention it on the README.

You still need documentation for the internal API. You also need a separate section of your test suite for internal tests and a “public” test suite that only tests the specified behaviour of the public API and nothing more. Having your internals undocumented is worse in the long run than having no clearly defined public API.

If your upstream dependencies are not using SemVer, you can either “vendor in” code in your project’s source control, specify a known good range of versions, or make the build system download a tarball of a compatible release. If an upstream dependency uses SemVer correctly, you only have to specify the major version and a minimum minor version. Of course it can still make sense to re-write your code and bump requirements to a higher version. If a new release bumps the required versions of upstream libraries, well, that might affect downstream users too. Better document what you would do in this case!

You should probably give some more thought to versioning, build systems, and run-time concerns. Can different major versions of your library be installed on the same system? In different prefixes? Can the same program accidentally depend on two different major versions of your library?

If you do all this properly, downstream projects built against version 4.0 of your library can depend of version 4.X.X and still work. Well, that is until somebody upgrades their mac, or until somebody upgrades their debian to a version that runs wayland by default, but doesn’t have PyGame compiled with wayland support...

If you don’t, you can still say “We use SemVer“, and just bump the major version number with every release. It’s just not very useful.

[mentalisttraceur-software]

Automating SemVer

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.

I don't have a solution yet, just a vision: when you're ready to release, a tool runs your new code against your tests, but not just the current tests, the tests from the previous release too, and tells you what your next SemVer number is; the only time it's wrong is when you write bad or incomplete tests.

[mentalisttraceur-software]

A major problem between SemVer and human intuition is that people feel a bump of the first version number indicates "big" and "significant" changes, but the best way to use SemVer would cause most bumps of the first version number to be tiny insignificant tweaks, most of which only break the API in subtle edge cases that almost no one is using or in trivial ways that are easy to fix.

[mentalisttraceur-software]

SemVer for Non-Releases

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.

But if you must cram it into a form that SemVer validators accept, I recommend viewing SemVer less like a human and more like a machine: each version "means", first and foremost, what it formally encodes, not the human words and expectations around it, so when deciding how to communicate non-releases in SemVer, that's the meaning to lean on most.

[mentalisttraceur-software]

We Are Not Neurotic Enough To Do SemVer

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.

Let's say in a single day you had three emergency hotfixes, each of which had to go out so fast that they couldn't be bundled into one release, and each one technically was a breaking change in some obscure corner of your API, if you're being really picky. If you find yourself resisting bumping the major version three times in a single day in that scenario, then SemVer is not for you.

[stxalq]

people yelling at the npm devs to follow the semver spec on prerelease and build metadata versions, but if the spec says MAY then that's truly an optional feature and RFC 2119 says you MUST be prepared to interoperate with an implementation that omits said feature stfu and eat shit cope

[stxalq]

it's wild to me that people try to use semver for UI, are we really trying to say we're explicitly maintaining backwards compatibility with the Human Being?