Hi everyone, I would like to start a discussion about what kind of API stability guarantees we want to provide to our users. The Flink community already agreed on some stability guarantees, but these guarantees were only communicated via the ML and not properly documented [2]. Moreover, I've seen more and more complaints about breaking changes (some rightful and others not) on the ML recently [3] because we rarely mark our APIs as stable. This motivated this FLIP.
The proposal first concentrates on source API stability guarantees. Binary stability guarantees are explicitly left out for a follow-up discussion. In essence, the proposal follows our current stability guarantees while updating the guarantees for @PublicEvolving that we are already providing w/o having stated them. Moreover, this FLIP proposes some guidelines for determining the stability guarantees for an API object, how to evolve them and some additional requirements for the return and parameter types of methods. All in all, I hope that this proposal is more reflecting our current understanding of stability guarantees than being controversial. One of the outcomes of this FLIP should be to properly document these guarantees so that it is easily discoverable and understandable for our users. Moreover, I hope that we can provide more stable APIs our users can rely and build upon. There will be a follow-up FLIP discussing the problem of how to make sure that APIs become stable over time. Looking forward to your feedback. [1] https://cwiki.apache.org/confluence/x/IJeqCw [2] https://lists.apache.org/thread/5jm25783oq5svyk7rr8g1gly2ooxqhjr [3] https://lists.apache.org/thread/kzhfc3t6omzo2kyo8zj9yxoh8twq5fzr Cheers, Till
