This seems like a nice idea on the face of it, but it's a lot less simple (who decides what's major and what isn't) and plus, when you introduce a "small" breaking change you have no idea what impact that's going to have downstream. It could be a really big deal for a client. The fact that it's a breaking change by definition means it's going to be a problem for someone and you really have no way to know how deeply entrenched that small piece of API surface is.

What bothers me about the current trends in release management is that there is way too much emphasis on iterating quickly, even for libraries where that's completely inappropriate.

It's much better to just put all your breaking changes into an unstable branch and only merge to stable (and change version numbers) infrequently, when you're sure the dust has settled. Anyone that really needs the latest updates can pull the unstable branch at their own risk, but everyone else doesn't have their build broken every other day. This is a really serious problem in the JavaScript ecosystem right now (even disregarding the left-pad debacle).

> a smaller but necessary change in a couple of the many functions of an API.

You can do that as much as you want in version 0.x.x

Get to v1 when you figured out the API and it is stable.

You can only do that once. Once you hit v1, if you introduce new APIs later, there's no "grace period" to make small breaking changes to those APIs.

In my case, the library that I avoided making breaking changes to because I didn't want to bump the major version was already on v2, and I didn't want to make it v3 after just a few weeks at v2.

On the words of Rich Hickey, why break people code at all?

Introduce the new APIs in a new namespace, class, module, new function name, whatever.

Maintainability? You now have two APIs to maintain instead of one.

Let's think about it for one second...

Either you write one new function yourself, or you force all API users to rewrite their functions to accommodate you.

The choice will be a show of what you value more: yourself or your users.

The old one can eventually make use of the new one internally, while not breaking everyone's code.

When adding new APIs to a v1+ library, the new APIs should be marked experimental and require some sort of flag to use.

This allows for new APIs to bake before having the experimental flag removed and stability guarantees introduced.

Very few languages actually allow for that sort of thing.

You can document it as well, language support is nice but not required.

This can be solved by adding some sort of annotation or documentation to new api's.

In RxJava [1], parts of the API are marked with @Experimental or @Beta. @Experimental provides no guarantees, while @Beta only guarantees no breakage in the same minor version.

[1] https://github.com/ReactiveX/RxJava