Hi Stefan, Thanks for the comments. I agree the API stability and compatibility guarantees should be clear. I think we need to answer the following four questions in order to complete the the public API stability and compatibility story:
*1. What is the scope of public interfaces?* We actually already have a definition of public interfaces in the FLIP[1] wiki, it is basically anything that is sensible to the users, including packages, classes, method signature and behavior (blocking v.s. non-blocking, for example), metrics, configurations, CLI tools and arguments, and so on. *2. What API changes can happen across different versions?* FLIP-196 answers the first question by defining in which versions programming APIs (methods and classes annotated with "Public", "PublicEvolving" or "Experimental") can have breaking changes. This allows us to get rid of deprecated APIs in patch / minor / major versions, while providing a clear expectation for our users. *3. When can breaking changes happen?* This FLIP tries to answer the second question, i.e. how users can adapt to breaking changes. We should avoid sudden API changes between two versions, and always leave time for the users to have a planned migration away from breaking changes. This basically means we will always take two steps when making breaking changes: 1. Introduce the new API (if needed), and mark the old API as deprecated. 2. After some time, which are the migration periods defined in this FLIP, remove the old API. And in this FLIP, we would like to define the exact length of the migration period. It is going to be a trade-off between the maintenance cost of deprecated APIs and the time users have to migrate away from those deprecated APIs. In this FLIP we want to define the minimum lengths of the migration periods. *4. How do users upgrade to Flink versions with breaking changes?* With the answers to the above three questions, the user upgrade path should be simple and clear: 1. upgrade to a Flink version that contains both the deprecated and new API. 2. have a planned migration to move to the new API. 3. upgrade to later Flink versions in which the code of the deprecated API is removed. So, it looks like our story for API stability and compatibility would be complete with this FLIP. Thanks, Jiangjie (Becket) Qin On Tue, Jun 13, 2023 at 12:30 AM Stefan Richter <srich...@confluent.io.invalid> wrote: > 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 > >
