Currently pretty much every maintainer has such a different idea of what constitutes a major/minor/patch change that I don’t really trust any version number to be insightful about the size of the change or difficulty updating to the new version until I’ve followed a library for a while and have seen several releases from the same person. As soon as you add a new standard for versioning someone will question if something really is a major enough breaking change or not or if they’ve been stuck on one epoch for too long or long enough and we’re back at the exact same situation as current.

Also, my view is that it’d be better if a version was comprised of 4 numbers instead of 3:

<marketing/product version>.<breaking changes>.<feature add-on>.<fix>

Making my point. Both were breaking in their early existence.

If you have found the new better interface, I bet it is to be named distinctly.

Because a better interface automatically leads to a better name? When I switch the argument order, there is no need for a new name and it would be worse to give it a ‘forced’ new name while the ‘old’ one was perfectly describing the function in the shortest way.

Plant warning for obsoletion

Again: in new libs it is polution imho . Break early and take the penalty. Once you are ‘too big to fail’ there will be enough times you have to ‘polute’ the code base with functions obsoletion. Just as you can see in both examples you provided. Breaking-strategy when small, obsoleting when larger.

That’s all I gotta say. Back on topic: epoch semver!

I am with you here:

1. Epoch SemVer does not seem to tackle the nastiest problem and you outlined it well: how do we not do a major version bump if we changed 1-2 functions? (This of course assumes we had to and it was not a capricious whim.)
2. Early on the libraries must be allowed to break the API / contract. I think many people, myself included, expect the 0.X.Y versions to be unstable and that any unattended upgrade is at your own risk. This is a compromise with by-the-book SemVer but that’s also a criticism to those who invented it: they did not think of that use-case, and it’s a very common use-case.

I am about to release a library in a few more weeks. I will enlist at least two LLMs to criticise structure and naming and general contracts and function locations. I’ll ask them to be ruthless and will consider each bit of info they give me. I’ll also take one final look myself after.

But the top of the README.md will contain something like the following:

### Compatibility promise

For the moment: none. Note that the library is currently in its `v0` iteration. Once the author feels it has been used enough time and by enough people that the contract is not confusing to users and looks stable, `v1` and on will be released which will then lead to a firmer compatibility promise. In the meantime please always check the changelog before upgrading! Breaking changes will be explicitly marked as such.

Semver explicitly allows breaking changes below v1: