A proposal for API stability: marking functions as experimental

Development
1

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.

2

Sounds like a good idea!

We would probably need to mark these functions in a consistent way in the documentation as well. We could introduce an extra documentation tag (like \experimental) and replace it with a short paragraph typeset as a warning admonition.

2 Likes
3

Yes, I agree, it is a good idea to get new functionality out there more quickly, without waiting for it to be complete.

Indeed, it should be clearly marked as experimental, and always raise a warning that it is experimental.

So for all non-experimental functions we provide semantic versioning guarantees, while for experimental functions anything goes (as if they belonged to a development 0.x release).