Hi, Thanks a lot for bringing up this topic and for the initial proposal. As more and more people are looking into running Flink as a continuous service this discussion is becoming very relevant.
What I would like to see is a clearer definition for what we understand by stability and compatibility. Our current policy only talks about being able to “compile” and “run” with a different version. As far as I can see, there is no guarantee about the stability of observable behavior. I believe it’s important for the community to include this important aspect in the guarantees that we give as our policy. For all changes that we do to the stable parts of the API, we should also consider how easy or difficult different types of changes would be for running Flink as a service with continuous delivery. For example, introducing a new interface to evolve the methods would make it easier to write adapter code than changing method signatures in-place on the existing interface. Those concerns should be considered in our process for evolving interfaces. Best, Stefan <https://www.confluent.io/> Stefan Richter Principal Engineer II Follow us: <https://www.confluent.io/blog?utm_source=footer&utm_medium=email&utm_campaign=ch.email-signature_type.community_content.blog> <https://twitter.com/ConfluentInc> > On 11. Jun 2023, at 14:30, Becket Qin <becket....@gmail.com> wrote: > > Hi folks, > > As one of the release 2.0 efforts, the release managers were discussing our > API lifecycle policies. There have been FLIP-196[1] and FLIP-197[2] that > are relevant to this topic. These two FLIPs defined the stability guarantee > of the programming APIs with various different stability annotations, and > the promotion process. A recap of the conclusion is following: > > Stability: > @Internal API: can change between major/minor/patch releases. > @Experimental API: can change between major/minor/patch releases. > @PublicEvolving API: can change between major/minor releases. > @Public API: can only change between major releases. > > Promotion: > An @Experimental API should be promoted to @PublicEvolving after two > releases, and a @PublicEvolving API should be promoted to @Public API after > two releases, unless there is a documented reason not to do so. > > One thing not mentioned in these two FLIPs is the API deprecation process, > which is in fact critical and fundamental to how the stability guarantee is > provided in practice, because the stability is all about removing existing > APIs. For example, if we want to change a method "ResultFoo foo(ArgumentFoo > arg)" to "ResultBar bar(ArgumentBar arg)", there will be two ways to do > this: > > 1. Mark method "foo" as deprecated and add the new method "bar". At some > point later, remove the method "foo". > 2. Simply change the API in place, that basically means removing method foo > and adding method bar at the same time. > > In the first option, users are given a period with stability guarantee to > migrate from "foo" to "bar". For the second option, this migration period > is effectively 0. A zero migration period is problematic because end users > may need a feature/bug fix from a new version, but cannot upgrade right > away due to some backwards compatible changes, even though these changes > perfectly comply with the API stability guarantees defined above. So the > migration period is critical to the API stability guarantees for the end > users. > > The migration period is essentially how long a deprecated API can be > removed from the source code. So with this FLIP, I'd like to kick off the > discussion about our deprecation process. > > https://www.google.com/url?q=https://cwiki.apache.org/confluence/display/FLINK/FLIP-321%253A%2BIntroduce%2Ban%2BAPI%2Bdeprecation%2Bprocess&source=gmail-imap&ust=1687091523000000&usg=AOvVaw0h_j72PiGBNM3BFmuHUOis > > Comments are welcome! > > Thanks, > > Jiangjie (Becket) Qin > > [1] > https://www.google.com/url?q=https://cwiki.apache.org/confluence/display/FLINK/FLIP-196%253A%2BSource%2BAPI%2Bstability%2Bguarantees&source=gmail-imap&ust=1687091523000000&usg=AOvVaw0VDOsdIOFCOsGLlpPJq-ZD > [2] > https://www.google.com/url?q=https://cwiki.apache.org/confluence/display/FLINK/FLIP-197%253A%2BAPI%2Bstability%2Bgraduation%2Bprocess&source=gmail-imap&ust=1687091523000000&usg=AOvVaw11GfC5R4cD44a8amORO8EY
