Description
What is your issue?
We try pretty hard to maintain backwards compatibility in xarray, and have informative deprecation cycles before any breaking changes. But this feature of the library isn't super-well advertised in the docs. The only places I can find it mentioned are deep in the contributing guide and the FAQ question about what's not public and stable API.
I want to add another FAQ question that makes an explicit promise, something like:
How stable is Xarray's API?
Xarray tries very hard to maintain backwards compatibility between released versions. Whilst we do occasionally make breaking changes in order to improve the library, we try to signpost changes with
DeprecationWarningsfor many (6+?) months in advance. (An exception is bugfixes - which we try to fix as soon as we notice them.) Our test-driven development practices help to ensure any accidental regressions are caught. This philosophy applies to everything in the public API.
That is my understanding of what we already do, but I think it's useful for it to be in writing.
cc @shoyer let me know if you think this is too strong / weak a promise to make explicitly