Reasons I dislike semver

• If the MAJOR changes, you know something intentionally broke, but you don't know what
• You can figure out what broke by seeing your own code break, or perhaps ahead of time by reading the release notes.
• Frequently in practice there are no useful release notes about the breakage, though. If they're following semver strictly, you can maybe find details in documentation, and review changes to documentation when there are no useful release notes. You could also step through all the commits -- but we're trying to avoid that effort, no?
• This leads to interpreting a version number as maybe-care.don't-care.don't-care
• And so the only possible benefit is increased laziness by ignoring the don't-cares, because the intent is that you can upgrade freely until the MAJOR changes
• But this laziness is bad, and in practice doesn't turn out so nicely, because changing the MAJOR only captures intentional breaking changes, and not the very common unintentional breaking changes
• That is, if your goal is just to prevent breaking, intentional or not, you can't even trust a PATCH change, because bugs happen
• Plus, you might actually care about the smaller bug fixes and new features! You should really spend effort to see what changed and consider updating, when there's an update. It might even be critical to your program's security. Sorry, you can't be lazy without consequence.
• Additionally semver makes no requirements on granularity. Change one thing that breaks? Update the MAJOR. Change many things completely (version 2.0 baby!) in a way that requires most everyone to do a rewrite? Update the MAJOR. Which one of those is this update? You have to look to find out.
• Not everyone uses semver, and nor will they ever thankfully, but this means you can't be lazy for everything. Because of scale, it's less effort to be consistent with how you handle updates for all your dependencies, rather than dividing processes and trying to be lazier for semver'd libraries.
• So even with some semver, you need to have automated builds and tests at a minimum, this lets you try every new version regardless of whether the MAJOR changed or not, regardless if the library is semver'd or not, and see if it breaks you in a way you can easily detect
• In practice, when breaking changes happen, the response of the project is one of three not very helpful options, the second being the best but you still experienced breakage
1. It was intentional, revert or deal with it
2. It was unintentional, revert or wait until we push a new patch to restore behavior
3. It was unintentional, but we like it, so we'll bump the MAJOR and re-release, revert or deal with it
• If it does break, most people don't care whether that break was intentional or not, they're mad that they need to work around it. Those three responses aren't helpful.

Summarizing: I find semver useless (it saves no effort or frustration in practice) and even harmful (it condones making breaking changes without recognizing that people don't like breakages, intentional or not), and so is not worth standardizing on.

The better thing to do as a library author is to not break APIs! When you have this attitude it's very possible to have non-breaking APIs for a long time, much like when you embrace an immutable-by-default language you learn that you don't need as much mutation as you thought.

One way to do it is to maintain multiple versions of your API within the same program, and support all versions indefinitely. It's not as bad as it sounds, and in many cases might just mean exporting a "myFunc2" and updating documentation that users should really use that one. You can even add instrumentation to discover usage, and consider removing if you find no one really is using the disfavored entry point, but it's better to just not break things ever.

See Full Post and Comments