Something I've never quite understood about semantic versioning. Sometimes fixing a bug is a breaking change, especially if someone is relying on that behavior to be bugged. How does one make the distinction?

Remember, versioning rules are like D&D. The purpose of the rules is to give you a framework to operate in that is easily understood in the vast majority of situations, not to comprehensively define every aspect. You don't get any rewards for following the rules, after all. When things get weird, you just ask the DM, they make a ruling, and then you keep the game moving forward.

There's always going to be corner cases. Fortunately, there is always a person available to act as a referee.

So do that explain why reading the OpenSSL code is like trying to translate some dead wizard's spellbook?

See https://www.youtube.com/watch?v=OIkwABECfR0 for a discussion on how this can be useful.

Yes, that's exactly what was on my mind. I'd just watched it yesterday, and the similarity struck me.

Well, that and the Pirate Code: "The Code is more what you call guidelines, than actual rules...."

I'm remembering this analogy for next time!

If the bug wasn't documented and the user effectively relied on "undefined behavior" I don't think it constitutes a breaking change. Like if a function called with certain parameters causes an unexpected crash, and a user decided to use that to quit the application, you can't reasonably be expected to maintain that behaviour.

If the bug was that a well documented function actually behaved differently than was expected but still consistently (like a string function that was supposed to return a number of characters but really returned a number of bytes) then yeah, that's a breaking change.

In practice the line can be fuzzy of course, but I find that it's not usually to hard to decide what constitutes a breaking change and what doesn't.

I think this is why they specifically call out ABI changes. A major release is one that changes the ABI/API - i.e. the C function definitions have changed and you are forced to recompile. A bugfix that breaks someone's workflow but does not change the ABI is not a major release.

> Sometimes fixing a bug is a breaking change

Apart from the ABI thing, which is pretty clear-cut - most bug files should not break the public Api - but sometimes the api spec is buggy. Then bug fix becomes a breaking change.

Assume that ssl certs are never actually checked[1] - this is typically a bug - and a bad situation. I would probably assume fixing such a bug would be a breaking change, even though it's a case of "omg, hair on fire this never was working" - and clearly a bug...

[1] yeah that's a real example https://www.python.org/dev/peps/pep-0476/

If you can't re-link with the new library, it's no longer ABI compatible and thus it's a major version change.

If you can re-link with the new library but something no longer works, you need to emit lots of very loud warnings when code calls that function.

> breaking change

Seems like Major increment to me. But! If the fix is breaking some previous undefined behaviour to work correct then I think Minor with relnote. But! If the code is not in wide use, bump Patch and move on.

There's an XKCD for that: https://xkcd.com/1172/