Humane SemVer is one of my attempts at fixing SemVer. It's meant to get you to think a bit more about your versioning. If you're interested in a much more rigorous fix, check out SemVer Prime!

Humane SemVer

Humane SemVer is a convention I'd like you to consider for your software projects. It is strictly a subset of SemVer, which means you can use it without fear of breaking SemVer-based tooling.

Humane SemVer works by gently nudging you to include more meaning in your versions:

• To do so, simply bump your versions by numbers that scale with "how much pain" goes into up/down-grading:
  • Changed a single function's name or tweaked its signature? Bump by 1!
  • Fundamentally changed the way you interact with a core feature? Bump by 50!
  • Changed an invariant in a way that can't be detected at compile time? Go to jail you monster!
• Stop fearing big numbers! So what if you hit version 42.0.0 in a few months? We're developers! We regularly think of numbers above 2³²!
• Inform your users of your usage of Humane SemVer, explaining in your changelog why that even though 212.0.0 came only a week after 211.0.0, they don't even need to change their code to use it because it's "just a change in the memory layout of SendHandle, and we treat ABI breaks as 'tiny majors', but hey, 20% more bandwidth!".
  Want to know how they got to 211.0 in the first place? Unpack this spoiler tag!

  • 1.0 (I'll omit patch numbers for brevity) came out when John first finished writing homing-pigeon, a distributed systems library, and decided it was time to release it.
  • 2.0 and 3.0 came out of as John renamed a few methods in two steps when he discovered that the rest of the community used certain terms differently in the same problem space. John decided those were tiny bumps because the semantics stayed exactly the same and "Just find and replace and Bob's your uncle!".
  • Time goes on, John allies with Caitlin to found the Dove Networking Company, turning homing-pigeon into a product. They get plenty of funding and hire very clever people
  • Rupert proposes a brand new API: it's a total break, but the team decides to move to it due to how many bugs it could eliminate. Luckily, Caitlin had heard of Humane SemVer and asks that the release be branded 60.0, a stark jump from 3.15 that had been reached just last month.
  • Thanks to Velma's efforts, homing-pigeon's network overhead could get 60% lower! But upgrading a distributed system library can be pretty gnarly; they decide to act extremely carefully:
    • A first transition version, capable of using both versions of the protocol, is released as 60.3.
    • It was followed by 6 minors, over the following year, reaching 60.9. A tool was also made available to help detect if versions that couldn't speak the new protocol were still online.
    • Finally, they got rid of the old protocol's codebase in 200.0. This huge bump was meant to alert users that even though they could upgrade from 60.0 to 200.0 without so much as changing a character of their code if they wanted, that upgrade would probably not be painless.
  • 200.0 was also homing-pigeon's first ABI-stable release: from now on, any change in the library's ABI will lead to a major bump. In fact, the next 11 versions were all majors that only contained ABI changes.

With just a few integers, it's hard (but not impossible) to convey intricate meaning. But that's what changelogs are for! The true goal of Humane SemVer is to reduce the strange pressure we feel from a set of 3 tiny integers, while retaining the usefulness they do have for automated tools.

Does Humane SemVer solve everything? No. Do I find it better than SemVer Classic? Yes! I'd be very happy to hear your suggestions for usages of SemVer that stay conform to it while being also more human friendly!

Comments