Hi Chesnay and Stefan, Thanks for the feedback and sorry for the confusion about Public API deprecation. I just noticed that there was a mistake in the NOTES part for Public API due to a copy-paste error... I just fixed it.
To clarify on the deprecation of "Public" APIs. The FLIP does not propose to remove the code of "Public" APIs with a minor version bump. The Public APIs still can only be removed with a major version bump. What this FLIP enforces is the minimum migration period in addition to this rule. For example, if the next version after 1.19 is 2.0, without the migration period specified in this FLIP (that is 2 minor versions), we can technically remove a Public API from 1.19 right away because the next release changes the major version. However, this leaves no time for the users to migrate. With this FLIP, we have to keep the deprecated API for at least 2 minor releases, so we have to keep it in at least 2.0 and 2.1 due to this FLIP, and also all the 2.x versions because removing a Public API requires a major version bump. Therefore, that deprecated Public API can only be removed in 3.0. As another example, if after 1.19, we deprecate a Public API in 1.20, and 1.21, then we release 2.0. In this case, the deprecated Public API has been kept for 2 minor releases (1.20 and 1.21), we can remove it in 2.0 if we want to. We can also choose to keep it there for longer if we want to. But if we decide to keep the deprecated API in 2.0, we can only remove it in 3.0. The "carry recent Public APIs forward into the next major release" thing > seems to presume a linear release history (aka, if 2.0 is released after > 1.20, then there will be no 1.21), which I doubt will be the case. The > idea behind it is good, but I'd say the right conclusion would be to not > make that API public if we know a new major release hits in 3 months and > is about to modify it. With a regular schedule for major releases this > wouldn't be difficult to do. I agree if we know a brand new Public API (not a replacement for deprecated API) will be changed in 3 months, it would not make sense to introduce that in the current major version in the first place. But that is a different discussion from the deprecation process. The deprecation process is mainly for the API that is already there. In the other case, if we are talking about a new API as a replacement for a deprecated API, we have to introduce it in the current major version, so that users can migrate from the deprecated API to the new replacement API in the current major version, which allows them to migrate to the next major version, which only has the new API, once it is released. Regarding the linear v.s. non-linear process, if we can enforce the migration period, I wonder if we still need to release 1.X after 2.x is released. The idea behind this is that if we can make the major version upgrade experience smooth for the users, we don't need to release 1.x anymore after 2.x is released. Instead we can focus on evolving 2.x. With a decent migration period, users should be able to upgrade to 2.x from 1.x because they have been given time to migrate away from all the deprecated APIs in 1.x before 2.0 is released, that is at least 2 minor releases for Public APIs, 1 minor release for PublicEvolving APIs and 1 patch release for Experimental APIs. It would be valuable if we can avoid releasing minor versions for previous major versions. Releasing a minor version for old major versions usually means we are backporting some feature to the previous major version, which likely introduces non-trivial burdens. If users want new features, they should upgrade to 2.x. Thanks, Jiangjie (Becket) Qin On Tue, Jun 13, 2023 at 10:24 PM Chesnay Schepler <ches...@apache.org> wrote: > On 13/06/2023 12:50, Jing Ge wrote: > > One major issue we have, afaiu, is caused by the lack of > housekeeping/house > > cleaning, there are many APIs that were marked as deprecated a few years > > ago and still don't get removed. Some APIs should be easy to remove and > > others will need some more clear rules, like the issue discussed at [1]. > > This is by design. Most of these are @Public APIs that we had to carry > around until Flink 2.0, because that was the initial guarantee that we > gave people. > > > As for the FLIP, I like the idea of explicitly writing down a > deprecation period for APIs, particularly PublicEvolving ones. > For Experimental I don't think it'd be a problem if we could change them > right away, > but looking back a bit I don't think it hurts us to also enforce some > deprecation period. > 1 release for both of these sound fine to me. > > > My major point of contention is the removal of Public APIs between minor > versions. > This to me would a major setback towards a simpler upgrade path for users. > If these can be removed in minor versions than what even is a major > release? > The very definition we have for Public APIs is that they stick around > until the next major one. > Any rule that theoretically allows for breaking changes in Public API in > every minor release is in my opinion not a viable option. > > > The "carry recent Public APIs forward into the next major release" thing > seems to presume a linear release history (aka, if 2.0 is released after > 1.20, then there will be no 1.21), which I doubt will be the case. The > idea behind it is good, but I'd say the right conclusion would be to not > make that API public if we know a new major release hits in 3 months and > is about to modify it. With a regular schedule for major releases this > wouldn't be difficult to do. >
