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