Here’s an idea inspired by how Mathematica has extended its API recently.
Getting the API right the first time for some new functionality area (or even a single function) is hard. If you do it too quickly, it’ll probably not be great. It will limit extensions to the functionality or it will not be possible to keep it consistent with new functions that we add in the future. But if you spend too much time on it, that’s too much of a drag on development.
One possible solution:
If we are not sure that the API for some newly added function is perfect, we mark it as “experimental” in the documentation. This would mean that we reserve the right to change it without bumping the major version in the MAJOR.MINOR.PATCH scheme.
This would allow for more dynamic development. When writing functions for an entire new functionality area, we will not need to complete the entire set of functions, and verify that they are all consistent with each other, before releasing them. We can release a single function as soon as it’s done, with the caveat that it may get modified in the future. Ideally, it will not need to be modified. We should still try to get it right the first time. But we reserve the right to make changes, should they be necessary to ensure that a complete set of related functions fits well together and works well together.
To be clear, I am not suggesting to mark every single new function as “experimental” and keep it that way for a version or two. It should be a possibility, to be used when appropriate and neessary. I think this would be a useful extension to standard semantic versioning.