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://cwiki.apache.org/confluence/display/FLINK/FLIP-321%3A+Introduce+an+API+deprecation+process Comments are welcome! Thanks, Jiangjie (Becket) Qin [1] https://cwiki.apache.org/confluence/display/FLINK/FLIP-196%3A+Source+API+stability+guarantees [2] https://cwiki.apache.org/confluence/display/FLINK/FLIP-197%3A+API+stability+graduation+process
