FYI: The API and binary compatibility check has been activated [1]. [1] https://issues.apache.org/jira/browse/FLINK-17844
Cheers, Till On Mon, May 18, 2020 at 1:11 PM Chesnay Schepler <ches...@apache.org> wrote: > yes > > On 18/05/2020 13:05, Piotr Nowojski wrote: > > How would we enforce this change? That we would enable different, more > strict compatibility checks on the `release-1.x` branches? > > > > Piotrek > > > >> On 16 May 2020, at 08:33, Congxian Qiu <qcx978132...@gmail.com> wrote: > >> > >> Sorry for the late jump in. > >> > >> +1 to keep the compatibility of @PublicEvolving between minor > >> releases(x.y.a -> x.y.b), as a user I always think this as a bug-fix > >> release, break the compatibility between minor releases may give users a > >> surprise. > >> > >> As the previous emails said, how and when will a @PublicEvolving > >> become @Public, and I'm not sure if we can have a technical solution to > >> keep such a rule. (In my opinion, check such things -- change > >> @PublicEvolving to @Public -- manually may not so easy) > >> > >> Best > >> Congxian > >> > >> > >> Till Rohrmann <trohrm...@apache.org> 于2020年5月15日周五 下午9:18写道： > >> > >>> The vote thread can be found here > >>> > >>> > https://lists.apache.org/thread.html/rc58099fb0e31d0eac951a7bbf7f8bda8b7b65c9ed0c04622f5333745%40%3Cdev.flink.apache.org%3E > >>> . > >>> > >>> Cheers, > >>> Till > >>> > >>> On Fri, May 15, 2020 at 3:03 PM Till Rohrmann <trohrm...@apache.org> > >>> wrote: > >>> > >>>> I completely agree that there are many other aspect of our guarantees > and > >>>> processes around the @Public and @PublicEvolving classes which need > to be > >>>> discussed and properly defined. For the sake of keeping this > discussion > >>>> thread narrowly scoped, I would suggest to start a separate discussion > >>>> about the following points (not exhaustive): > >>>> > >>>> - What should be annotated with @Public and @PublicEvolving? > >>>> - Process for transforming @PublicEvolving into @Public; How to ensure > >>>> that @PublicEvolving will eventually be promoted to @Public? > >>>> - Process of retiring a @Public/@PublicEvolving API > >>>> > >>>> I will start a vote thread about the change I proposed here which is > to > >>>> ensure API and binary compatibility for @PublicEvolving classes > between > >>>> bugfix releases (x.y.z and x.y.u). > >>>> > >>>> Cheers, > >>>> Till > >>>> > >>>> On Fri, May 15, 2020 at 6:33 AM Zhu Zhu <reed...@gmail.com> wrote: > >>>> > >>>>> +1 for "API + binary compatibility for @PublicEvolving classes for > all > >>> bug > >>>>> fix > >>>>> releases in a minor release (x.y.z is compatible to x.y.u)" > >>>>> > >>>>> This @PublicEnvolving would then be a hard limit to changes. > >>>>> So it's important to rethink the policy towards using it, as Stephan > >>>>> proposed. > >>>>> > >>>>> I think any Flink interfaces that are visible to users should be > >>>>> explicitly > >>>>> marked as @Public or @PublicEnvolving. > >>>>> Any other interfaces should not be marked as > @Public/@PublicEnvolving. > >>>>> This would be essential for us to check whether we are breaking any > user > >>>>> faced interfaces unexpectedly. > >>>>> The only exception would be the case that we had to expose a > >>> method/class > >>>>> due to implementation limitations, it should be explicitly marked it > >>>>> as @Internal. > >>>>> > >>>>> Thanks, > >>>>> Zhu Zhu > >>>>> > >>>>> Yun Tang <myas...@live.com> 于2020年5月15日周五 上午11:41写道： > >>>>> > >>>>>> +1 for this idea, and I also like Xintong's suggestion to make it > >>>>>> explicitly when the @PublicEvolving API could upgrade to @Public > API. > >>>>>> If we have the rule to upgrade API stable level but not define the > >>> clear > >>>>>> timeline, I'm afraid not everyone have the enthusiasm to upgrade > this. > >>>>>> > >>>>>> The minor suggestion is that I think two major release (which is > x.y.0 > >>>>> as > >>>>>> Chesnay clarified) might be a bit quick. From the release history > [1], > >>>>>> Flink bump major version every 3 ~ 6 months and two major release > gap > >>>>>> could only be at least half a year. > >>>>>> I think half a year might be a bit too frequent for users to collect > >>>>>> enough feedbacks, and upgrading API stable level every 3 major > >>> versions > >>>>>> should be better. > >>>>>> > >>>>>> [1] https://flink.apache.org/downloads.html#flink > >>>>>> > >>>>>> Best > >>>>>> Yun Tang > >>>>>> > >>>>>> > >>>>>> ________________________________ > >>>>>> From: Xintong Song <tonysong...@gmail.com> > >>>>>> Sent: Friday, May 15, 2020 11:04 > >>>>>> To: dev <dev@flink.apache.org> > >>>>>> Subject: Re: [DISCUSS] Stability guarantees for @PublicEvolving > >>> classes > >>>>>> ### Documentation on API compatibility policies > >>>>>> > >>>>>> Do we have any formal documentation about the API compatibility > >>>>> policies? > >>>>>> The only things I found are: > >>>>>> > >>>>>> - In the release announcement (take 1.10.0 as an example) [1]: > >>>>>> "This version is API-compatible with previous 1.x releases for > APIs > >>>>>> annotated with the @Public annotation." > >>>>>> - JavaDoc for Public [2] and PublicEvolving [3]. > >>>>>> > >>>>>> I think we might have a formal documentation, clearly state our > >>> policies > >>>>>> for API compatibility. > >>>>>> > >>>>>> - What does the annotations mean > >>>>>> - In what circumstance would the APIs remain compatible / become > >>>>>> incompatible > >>>>>> - How do APIs retire (e.g., first deprecated then removed?) > >>>>>> > >>>>>> Maybe there is already such kind of documentation that I overlooked? > >>> If > >>>>> so, > >>>>>> we probably want to make it more explicit and easy-to-find. > >>>>>> > >>>>>> ### @Public vs. @PublicEvolving for new things > >>>>>> > >>>>>> I share Stephan's concern that, with @PublicEvolving used for every > >>> new > >>>>>> feature and rarely upgraded to @Public, we are practically making no > >>>>>> compatibility guarantee between minor versions (x.y.* / x.z.*). On > the > >>>>>> other hand, I think in many circumstances we do need some time to > >>>>> collect > >>>>>> feedbacks for new features before we have enough confidence to make > >>> the > >>>>>> commitment that our APIs are stable. Therefore, it makes more sense > to > >>>>> me > >>>>>> to first make new features @PublicEvolving and then upgrade to > @Public > >>>>> in > >>>>>> the next one or two releases (unless there's a good reason to > further > >>>>>> postpone it). > >>>>>> > >>>>>> I think the key point is how do we make sure the @PublicEvolving > >>>>> features > >>>>>> upgrade to @Public. Maybe we can add a parameter to indicate the > >>>>> expected > >>>>>> upgrading version. E.g., a new feature introduced in release 1.10.0 > >>>>> might > >>>>>> be annotated as @PublicEvolving("1.12.0"), indicating that it is > >>>>> expected > >>>>>> to be upgraded to @Public in release 1.12.0. We can check the > >>>>> annotations > >>>>>> against the version automatically, forcing to either upgrad the > >>> feature > >>>>>> to @Public or explicitly postpone it by modifying the annotation > >>>>> parameter > >>>>>> (if there's a good reason). > >>>>>> > >>>>>> Additionally, we can do the similar for deprecated features / APIs, > >>>>>> reminding us to remove things annotated as @Deprecated at certain > >>> time. > >>>>>> Thank you~ > >>>>>> > >>>>>> Xintong Song > >>>>>> > >>>>>> > >>>>>> [1] https://flink.apache.org/news/2020/02/11/release-1.10.0.html > >>>>>> > >>>>>> [2] > >>>>>> > >>>>>> > >>> > https://ci.apache.org/projects/flink/flink-docs-master/api/java/org/apache/flink/annotation/Public.html > >>>>>> [3] > >>>>>> > >>>>>> > >>> > https://ci.apache.org/projects/flink/flink-docs-master/api/java/org/apache/flink/annotation/PublicEvolving.html > >>>>>> > >>>>>> > >>>>>> > >>>>>> On Thu, May 14, 2020 at 8:22 PM Stephan Ewen <se...@apache.org> > >>> wrote: > >>>>>>> I just want to throw in that we also need to rethink our policy > >>>>> towards > >>>>>>> using @PublicEvolving. > >>>>>>> > >>>>>>> We often introduce this easily (for every new feature) and rarely > >>>>> (almost > >>>>>>> never) upgrade it to @Public. This kind of leads the idea behind > >>>>> stable > >>>>>> API > >>>>>>> guarantees ad absurdum. > >>>>>>> > >>>>>>> I would suggest that we make @PublicEvolving an exception that > >>> needs a > >>>>>> good > >>>>>>> reason rather than for everything that is new (when we don't want > to > >>>>> be > >>>>>>> bothered with thinking about compatibility). > >>>>>>> > >>>>>>> > >>>>>>> On Thu, May 14, 2020 at 1:05 PM Xintong Song < > tonysong...@gmail.com > >>>>>>> wrote: > >>>>>>> > >>>>>>>> Thanks for the clarification. > >>>>>>>> +1 for keeping the current guarantees for @Public. > >>>>>>>> > >>>>>>>> Thank you~ > >>>>>>>> > >>>>>>>> Xintong Song > >>>>>>>> > >>>>>>>> > >>>>>>>> > >>>>>>>> On Thu, May 14, 2020 at 6:07 PM Till Rohrmann < > >>> trohrm...@apache.org > >>>>>>>> wrote: > >>>>>>>> > >>>>>>>>> Sorry for the confusion. @Public classes are guaranteed to be > >>>>> stable > >>>>>>>>> between releases x.y.z and x.u.v (minor and bug fix release; > >>>>> naming > >>>>>> is > >>>>>>>>> indeed a bit off here) and we can break it with major releases > >>>>> (x.0.0 > >>>>>>> and > >>>>>>>>> y.0.0). > >>>>>>>>> > >>>>>>>>> @Tison I would like to make what to include in the public API, > >>>>> hence > >>>>>>> what > >>>>>>>>> to annotate with @Public and @PublicEvolving, a separate > >>>>> discussion. > >>>>>>>>> Cheers, > >>>>>>>>> Till > >>>>>>>>> > >>>>>>>>> On Thu, May 14, 2020 at 11:48 AM tison <wander4...@gmail.com> > >>>>> wrote: > >>>>>>>>>> Thanks for starting this discussion! > >>>>>>>>>> > >>>>>>>>>> I agree turn on japicmp on PublicEvolving among bugfix releases > >>>>> is a > >>>>>>> nit > >>>>>>>>>> win. > >>>>>>>>>> > >>>>>>>>>> @Xintong Song <tonysong...@gmail.com> I think @Public > >>> guarantee > >>>>> is > >>>>>>> good > >>>>>>>>>> enough, the problem is a reachable 2.0 plan. > >>>>>>>>>> > >>>>>>>>>> My concern is more on classes that have no annotation but our > >>>>>>> developers > >>>>>>>>>> regard as "something that should be stable". Previously I was > >>>>>> required > >>>>>>>> to > >>>>>>>>>> keep compatibility of ClusterClient & HighAvailabilityServices > >>>>>> because > >>>>>>>>>> they > >>>>>>>>>> might be depended on by user. > >>>>>>>>>> > >>>>>>>>>> Best, > >>>>>>>>>> tison. > >>>>>>>>>> > >>>>>>>>>> > >>>>>>>>>> Dawid Wysakowicz <dwysakow...@apache.org> 于2020年5月14日周四 > >>>>> 下午5:08写道： > >>>>>>>>>>> I also like the proposal for keeping the binary compatibility > >>>>> of > >>>>>>>>>>> @PublicEvolving for bugfix releases. > >>>>>>>>>>> > >>>>>>>>>>> As for the @Public classes I think the current guarantees are > >>>>> good > >>>>>>>>>> enough. > >>>>>>>>>>> Best, > >>>>>>>>>>> > >>>>>>>>>>> Dawid > >>>>>>>>>>> > >>>>>>>>>>> On 14/05/2020 10:49, Jingsong Li wrote: > >>>>>>>>>>>> Thanks Till for starting this discussion. > >>>>>>>>>>>> > >>>>>>>>>>>> +1 for enabling the japicmp-maven-plugin for > >>> @PublicEvolving > >>>>> for > >>>>>>> bug > >>>>>>>>>> fix > >>>>>>>>>>>> releases. > >>>>>>>>>>>> Bug fix should just be user imperceptible bug fix. Should > >>> not > >>>>>>> affect > >>>>>>>>>> API > >>>>>>>>>>>> and binary compatibility. > >>>>>>>>>>>> > >>>>>>>>>>>> And even PublicEvolving api change for "y" release, we > >>> should > >>>>>>> expose > >>>>>>>>>> it > >>>>>>>>>>> in > >>>>>>>>>>>> dev mail list for discussing or a FLIP? > >>>>>>>>>>>> > >>>>>>>>>>>> BTW, public api can be changed by major releases? In > >>>>> annotation > >>>>>>>>>> comments: > >>>>>>>>>>>> "Only major releases (1.0, 2.0, 3.0) can break interfaces > >>>>> with > >>>>>>> this > >>>>>>>>>>>> annotation". > >>>>>>>>>>>> > >>>>>>>>>>>> Best, > >>>>>>>>>>>> Jingsong Lee > >>>>>>>>>>>> > >>>>>>>>>>>> On Thu, May 14, 2020 at 4:30 PM Till Rohrmann < > >>>>>>> trohrm...@apache.org > >>>>>>>>>>> wrote: > >>>>>>>>>>>>> Dear community, > >>>>>>>>>>>>> > >>>>>>>>>>>>> in the latest 1.10.1 bug fix release I introduced a binary > >>>>>>>>>> incompatible > >>>>>>>>>>>>> change to a class which is annotated with @PublicEvolving > >>>>> [1]. > >>>>>>>> While > >>>>>>>>>>> this > >>>>>>>>>>>>> change is technically ok since we only provide API and > >>>>> binary > >>>>>>>>>>> compatibility > >>>>>>>>>>>>> for @Public classes across releases, it raised the > >>> question > >>>>>>> whether > >>>>>>>>>> we > >>>>>>>>>>>>> can't do better. > >>>>>>>>>>>>> > >>>>>>>>>>>>> For our users it might be surprising and really annoying > >>>>> that > >>>>>>> they > >>>>>>>>>>> cannot > >>>>>>>>>>>>> simply upgrade to the latest bug fix release without > >>>>>> recompiling > >>>>>>>> the > >>>>>>>>>>>>> program or even having to change the source code of an > >>>>>>>> application. I > >>>>>>>>>>>>> believe we would provide a much better experience if we > >>>>> ensured > >>>>>>>> that > >>>>>>>>>> bug > >>>>>>>>>>>>> fix releases maintain API and binary compatibility also > >>> for > >>>>>>>>>>> @PublicEvolving > >>>>>>>>>>>>> classes. Hence my proposal would be to tighten the > >>> stability > >>>>>>>>>> guarantees > >>>>>>>>>>> the > >>>>>>>>>>>>> following way: > >>>>>>>>>>>>> > >>>>>>>>>>>>> * API + binary compatibility for @Public classes across > >>> all > >>>>>>>> releases > >>>>>>>>>>> (x.y.z > >>>>>>>>>>>>> is compatible to u.v.w) > >>>>>>>>>>>>> * API + binary compatibility for @PublicEvolving classes > >>> for > >>>>>> all > >>>>>>>> bug > >>>>>>>>>> fix > >>>>>>>>>>>>> releases in a minor release (x.y.z is compatible to x.y.u) > >>>>>>>>>>>>> > >>>>>>>>>>>>> This would entail that we can change @PublicEvolving > >>> classes > >>>>>> only > >>>>>>>>>> across > >>>>>>>>>>>>> minor/major releases. > >>>>>>>>>>>>> > >>>>>>>>>>>>> Practically this would mean that we enable the > >>>>>>> japicmp-maven-plugin > >>>>>>>>>>>>> for @PublicEvolving for bug fix releases. > >>>>>>>>>>>>> > >>>>>>>>>>>>> What do you think? > >>>>>>>>>>>>> > >>>>>>>>>>>>> [1] > >>>>>>>>>>>>> > >>>>>>>>>>>>> > >>> > https://lists.apache.org/thread.html/r293768d13d08149d756e0bf91be52372edb444c317535d1d5a496c3e%40%3Cdev.flink.apache.org%3E > >>>>>>>>>>>>> Cheers, > >>>>>>>>>>>>> Till > >>>>>>>>>>>>> > >>>>>>>>>>> > > > >
