[DISCUSS] Stability guarantees for @PublicEvolving classes

[Till Rohrmann]

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

[Xintong Song]

Thanks for bring this discussion up, Till.

+1 for guaranteeing API + binary compatibility for @PublicEvolving classes
for bug fix releases.

I have a bit concern on the compatibility of @Public classes though.
According to the JavaDoc, @Public requires classes to be stable
across minor releases (x.y.z vs. x.u.v), but can be broken by across major
releases (x.y.z v.s u.v.w). Further tighten the stability will leave us no
chance to remove outdated APIs annotated as @Public. AFAIK, there are
already many APIs annotated as @Public that we intend to remove with the
release 2.x. E.g., some deprecated constants in ConfigConstants.

Thank you~

Xintong Song



On Thu, May 14, 2020 at 4:30 PM Till Rohrmann <[hidden email]> 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
>

[Jingsong Li]

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 <[hidden email]> 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
>

--
Best, Jingsong Lee

[Chesnay Schepler-3]

So this is a terminology problem.

*Flink does not follow the major.minor.patch naming scheme.*

x.y.z is minor, x.y.0 is major, x.0.0 has no name as of right now.

Public API's may be broken in x.0.0, and Till is not suggesting to
change this.
What he is suggesting is that:

Public APIs may only be broken in x.0.0; as is current policy.
PublicEvolving APIs may only be broken in x.0.0 and x.y.0, but not
x.y.z; this would be new.

On 14/05/2020 10:47, Xintong Song wrote:

> Thanks for bring this discussion up, Till.
>
> +1 for guaranteeing API + binary compatibility for @PublicEvolving classes
> for bug fix releases.
>
> I have a bit concern on the compatibility of @Public classes though.
> According to the JavaDoc, @Public requires classes to be stable
> across minor releases (x.y.z vs. x.u.v), but can be broken by across major
> releases (x.y.z v.s u.v.w). Further tighten the stability will leave us no
> chance to remove outdated APIs annotated as @Public. AFAIK, there are
> already many APIs annotated as @Public that we intend to remove with the
> release 2.x. E.g., some deprecated constants in ConfigConstants.
>
> Thank you~
>
> Xintong Song
>
>
>
> On Thu, May 14, 2020 at 4:30 PM Till Rohrmann <[hidden email]> 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
>>

[dwysakowicz]

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 <[hidden email]> 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
>>
>

[tison]

Thanks for starting this discussion!

I agree turn on japicmp on PublicEvolving among bugfix releases is a nit
win.

@Xintong Song <[hidden email]> 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 <[hidden email]> 于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 <[hidden email]>
> 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
> >>
> >
>
>

[Till Rohrmann]

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 <[hidden email]> wrote:

> Thanks for starting this discussion!
>
> I agree turn on japicmp on PublicEvolving among bugfix releases is a nit
> win.
>
> @Xintong Song <[hidden email]> 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 <[hidden email]> 于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 <[hidden email]>
> > 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
> > >>
> > >
> >
> >
>

[Xintong Song]

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 <[hidden email]> 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 <[hidden email]> wrote:
>
>> Thanks for starting this discussion!
>>
>> I agree turn on japicmp on PublicEvolving among bugfix releases is a nit
>> win.
>>
>> @Xintong Song <[hidden email]> 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 <[hidden email]> 于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 <[hidden email]>
>> > 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
>> > >>
>> > >
>> >
>> >
>>
>

[Stephan Ewen]

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 <[hidden email]> 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 <[hidden email]>
> 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 <[hidden email]> wrote:
> >
> >> Thanks for starting this discussion!
> >>
> >> I agree turn on japicmp on PublicEvolving among bugfix releases is a nit
> >> win.
> >>
> >> @Xintong Song <[hidden email]> 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 <[hidden email]> 于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 <[hidden email]
> >
> >> > 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
> >> > >>
> >> > >
> >> >
> >> >
> >>
> >
>

[Xintong Song]

### 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 <[hidden email]> 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 <[hidden email]>
> 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 <[hidden email]>
> > 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 <[hidden email]> wrote:
> > >
> > >> Thanks for starting this discussion!
> > >>
> > >> I agree turn on japicmp on PublicEvolving among bugfix releases is a
> nit
> > >> win.
> > >>
> > >> @Xintong Song <[hidden email]> 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 <[hidden email]> 于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 <
> [hidden email]
> > >
> > >> > 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
> > >> > >>
> > >> > >
> > >> >
> > >> >
> > >>
> > >
> >
>

[Yun Tang]

+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 <[hidden email]>
Sent: Friday, May 15, 2020 11:04
To: dev <[hidden email]>
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 <[hidden email]> 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 <[hidden email]>
> 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 <[hidden email]>
> > 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 <[hidden email]> wrote:
> > >
> > >> Thanks for starting this discussion!
> > >>
> > >> I agree turn on japicmp on PublicEvolving among bugfix releases is a
> nit
> > >> win.
> > >>
> > >> @Xintong Song <[hidden email]> 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 <[hidden email]> 于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 <
> [hidden email]
> > >
> > >> > 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
> > >> > >>
> > >> > >
> > >> >
> > >> >
> > >>
> > >
> >
>

[Zhu Zhu]

+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 <[hidden email]> 于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 <[hidden email]>
> Sent: Friday, May 15, 2020 11:04
> To: dev <[hidden email]>
> 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 <[hidden email]> 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 <[hidden email]>
> > 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 <[hidden email]>
> > > 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 <[hidden email]> wrote:
> > > >
> > > >> Thanks for starting this discussion!
> > > >>
> > > >> I agree turn on japicmp on PublicEvolving among bugfix releases is a
> > nit
> > > >> win.
> > > >>
> > > >> @Xintong Song <[hidden email]> 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 <[hidden email]> 于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 <
> > [hidden email]
> > > >
> > > >> > 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
> > > >> > >>
> > > >> > >
> > > >> >
> > > >> >
> > > >>
> > > >
> > >
> >
>

[Till Rohrmann]

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 <[hidden email]> 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 <[hidden email]> 于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 <[hidden email]>
> > Sent: Friday, May 15, 2020 11:04
> > To: dev <[hidden email]>
> > 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 <[hidden email]> 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 <[hidden email]>
> > > 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 <[hidden email]>
> > > > 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 <[hidden email]>
> wrote:
> > > > >
> > > > >> Thanks for starting this discussion!
> > > > >>
> > > > >> I agree turn on japicmp on PublicEvolving among bugfix releases
> is a
> > > nit
> > > > >> win.
> > > > >>
> > > > >> @Xintong Song <[hidden email]> 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 <[hidden email]> 于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 <
> > > [hidden email]
> > > > >
> > > > >> > 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
> > > > >> > >>
> > > > >> > >
> > > > >> >
> > > > >> >
> > > > >>
> > > > >
> > > >
> > >
> >
>

[Till Rohrmann]

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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 于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 <[hidden email]>
>> > Sent: Friday, May 15, 2020 11:04
>> > To: dev <[hidden email]>
>> > 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 <[hidden email]> 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 <[hidden email]>
>> > > 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 <[hidden email]
>> >
>> > > > 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 <[hidden email]>
>> wrote:
>> > > > >
>> > > > >> Thanks for starting this discussion!
>> > > > >>
>> > > > >> I agree turn on japicmp on PublicEvolving among bugfix releases
>> is a
>> > > nit
>> > > > >> win.
>> > > > >>
>> > > > >> @Xintong Song <[hidden email]> 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 <[hidden email]> 于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 <
>> > > [hidden email]
>> > > > >
>> > > > >> > 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
>> > > > >> > >>
>> > > > >> > >
>> > > > >> >
>> > > > >> >
>> > > > >>
>> > > > >
>> > > >
>> > >
>> >
>>
>

[Congxian Qiu]

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 <[hidden email]> 于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 <[hidden email]>
> 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 <[hidden email]> 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 <[hidden email]> 于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 <[hidden email]>
> >> > Sent: Friday, May 15, 2020 11:04
> >> > To: dev <[hidden email]>
> >> > 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 <[hidden email]>
> 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 <[hidden email]
> >
> >> > > 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 <
> [hidden email]
> >> >
> >> > > > 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 <[hidden email]>
> >> wrote:
> >> > > > >
> >> > > > >> Thanks for starting this discussion!
> >> > > > >>
> >> > > > >> I agree turn on japicmp on PublicEvolving among bugfix releases
> >> is a
> >> > > nit
> >> > > > >> win.
> >> > > > >>
> >> > > > >> @Xintong Song <[hidden email]> 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 <[hidden email]> 于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 <
> >> > > [hidden email]
> >> > > > >
> >> > > > >> > 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
> >> > > > >> > >>
> >> > > > >> > >
> >> > > > >> >
> >> > > > >> >
> >> > > > >>
> >> > > > >
> >> > > >
> >> > >
> >> >
> >>
> >
>

[Piotr Nowojski-3]

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 <[hidden email]> 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 <[hidden email]> 于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 <[hidden email]>
>> 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 <[hidden email]> 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 <[hidden email]> 于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 <[hidden email]>
>>>>> Sent: Friday, May 15, 2020 11:04
>>>>> To: dev <[hidden email]>
>>>>> 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 <[hidden email]>
>> 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 <[hidden email]
>>>
>>>>>> 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 <
>> [hidden email]
>>>>>
>>>>>>> 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 <[hidden email]>
>>>> wrote:
>>>>>>>>
>>>>>>>>> Thanks for starting this discussion!
>>>>>>>>>
>>>>>>>>> I agree turn on japicmp on PublicEvolving among bugfix releases
>>>> is a
>>>>>> nit
>>>>>>>>> win.
>>>>>>>>>
>>>>>>>>> @Xintong Song <[hidden email]> 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 <[hidden email]> 于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 <
>>>>>> [hidden email]
>>>>>>>>
>>>>>>>>>> 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
>>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>

[Chesnay Schepler-3]

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 <[hidden email]> 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 <[hidden email]> 于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 <[hidden email]>
>>> 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 <[hidden email]> 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 <[hidden email]> 于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 <[hidden email]>
>>>>>> Sent: Friday, May 15, 2020 11:04
>>>>>> To: dev <[hidden email]>
>>>>>> 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 <[hidden email]>
>>> 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 <[hidden email]
>>>>>>> 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 <
>>> [hidden email]
>>>>>>>> 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 <[hidden email]>
>>>>> wrote:
>>>>>>>>>> Thanks for starting this discussion!
>>>>>>>>>>
>>>>>>>>>> I agree turn on japicmp on PublicEvolving among bugfix releases
>>>>> is a
>>>>>>> nit
>>>>>>>>>> win.
>>>>>>>>>>
>>>>>>>>>> @Xintong Song <[hidden email]> 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 <[hidden email]> 于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 <
>>>>>>> [hidden email]
>>>>>>>>>>> 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
>>>>>>>>>>>>>
>>>>>>>>>>>
>

[Till Rohrmann]

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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 于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 <[hidden email]>
> >>> 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 <[hidden email]> 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 <[hidden email]> 于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 <[hidden email]>
> >>>>>> Sent: Friday, May 15, 2020 11:04
> >>>>>> To: dev <[hidden email]>
> >>>>>> 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 <[hidden email]>
> >>> 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 <
> [hidden email]
> >>>>>>> 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 <
> >>> [hidden email]
> >>>>>>>> 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 <[hidden email]>
> >>>>> wrote:
> >>>>>>>>>> Thanks for starting this discussion!
> >>>>>>>>>>
> >>>>>>>>>> I agree turn on japicmp on PublicEvolving among bugfix releases
> >>>>> is a
> >>>>>>> nit
> >>>>>>>>>> win.
> >>>>>>>>>>
> >>>>>>>>>> @Xintong Song <[hidden email]> 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 <[hidden email]> 于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 <
> >>>>>>> [hidden email]
> >>>>>>>>>>> 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
> >>>>>>>>>>>>>
> >>>>>>>>>>>
> >
>
>