Hi Becket,
> *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. I agree with the scope that is defined by the annotation and think all observable behavior and also semantics should be covered by the policy. We should also review that all classes/methods/etc that are reachable through the API are annotated and define a sensible default in case something was missed. > > *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. I think the table has some contradiction with your first email for public API: > @Public API: can only change between major releases. Vs > Public At least 2 minor releases. I assume the entry in the table is a mistake? > > *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. This is where things get interesting when we want to make Flink fit for running as a service. So far our release and compatibility model is very developer centric (easy for development to move forward quickly) and not user friendly. In SaaS, there is not necessarily a user available to upgrade a job when the service undergoes an upgrade. And the expectation of a user would be that a service can update without breaking their continuously running jobs. We should answer the question what level of stability we want to provide our user in the future and elevate the Flink technology to a level that allows to create a service with continuous delivery across versions. Other software, like e.g. the Linux OS gives way stronger stability guarantees across versions, and I wonder if the discussion should not also explore how we can reach a comparable level of stability for Flink. > > 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 <mailto: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.google.com/url?q=https://www.confluent.io/&source=gmail-imap&ust=1687256610000000&usg=AOvVaw1dp7aAKHlg2BfLxN_FiCLh> >> Stefan Richter >> Principal Engineer II >> >> Follow us: < >> https://www.google.com/url?q=https://www.confluent.io/blog?utm_source%3Dfooter%26utm_medium%3Demail%26utm_campaign%3Dch.email-signature_type.community_content.blog&source=gmail-imap&ust=1687256610000000&usg=AOvVaw1sXHw7whbn-edlT6E0L2XS> >> <https://www.google.com/url?q=https://twitter.com/ConfluentInc&source=gmail-imap&ust=1687256610000000&usg=AOvVaw0HINEzFuW8kbEyJCdJMLui> >> >> >> >>> On 11. Jun 2023, at 14:30, Becket Qin <becket....@gmail.com >>> <mailto: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://www.google.com/url?q%3Dhttps://cwiki.apache.org/confluence/display/FLINK/FLIP-321%25253A%252BIntroduce%252Ban%252BAPI%252Bdeprecation%252Bprocess%26source%3Dgmail-imap%26ust%3D1687091523000000%26usg%3DAOvVaw0h_j72PiGBNM3BFmuHUOis&source=gmail-imap&ust=1687256610000000&usg=AOvVaw1Jm26zvqhwzD19JyokqEkR >>> >>> Comments are welcome! >>> >>> Thanks, >>> >>> Jiangjie (Becket) Qin >>> >>> [1] >>> >> https://www.google.com/url?q=https://www.google.com/url?q%3Dhttps://cwiki.apache.org/confluence/display/FLINK/FLIP-196%25253A%252BSource%252BAPI%252Bstability%252Bguarantees%26source%3Dgmail-imap%26ust%3D1687091523000000%26usg%3DAOvVaw0VDOsdIOFCOsGLlpPJq-ZD&source=gmail-imap&ust=1687256610000000&usg=AOvVaw0VAAYlNPEe5g6s7Ob_bX7_ >>> [2] >>> >> https://www.google.com/url?q=https://www.google.com/url?q%3Dhttps://cwiki.apache.org/confluence/display/FLINK/FLIP-197%25253A%252BAPI%252Bstability%252Bgraduation%252Bprocess%26source%3Dgmail-imap%26ust%3D1687091523000000%26usg%3DAOvVaw11GfC5R4cD44a8amORO8EY&source=gmail-imap&ust=1687256610000000&usg=AOvVaw1tBEpXV592z3on5y5X0sXD
