Re: Usage of PublicEvolving annotation
Hi all,
let me add a few more words on this topic:
The @PublicEvolving interface is kind of a staging annotation for
@Public. We still need to be careful when to change classes with
@PublicEvolving annotation. Usually, it still involves a proper
deprecation process over 1-2 releases to give downstream projects time
to adapt their implementation.
This is also the difference to @Experimental which can change
*immediately*, whereas @PublicEvolving is rather a "be careful there are
already users for this interface". The nice property about
@PublicEvolving is that you don't need to wait a major release (from 1.x
to 2.x which has not happened yet) to drop interfaces.
Regards,
Timo
On 11.07.22 07:27, Konstantin Knauf wrote:
Hi Blake,
thank you for reaching out. @PublicEvolving interface can only be changed
with a minor release of Apache Flink (e.g. 1.6). While the JavaDoc is
indeed ambiguous there was a FLIP recently that discussed this topic:
https://cwiki.apache.org/confluence/display/FLINK/FLIP-196%3A+Source+API+stability+guarantees
If you have time, feel free to open a PR to align the JavaDocs. Happy to
merge that.
Cheers,
Konstantin
Am So., 10. Juli 2022 um 07:07 Uhr schrieb Blake Wilson <
bl...@yellowpapersun.com>:
Hello,
I've noticed the usage of "PublicEvolving" in some Flink classes described
as follows
/**
* Annotation to mark classes and methods for public use, but with evolving
interfaces.
*
* Classes and methods with this annotation are intended for public use
and have stable behavior.
* However, their interfaces and signatures are not considered to be stable
and might be changed
* across versions.
*
* This annotation also excludes methods and classes with evolving
interfaces / signatures within
* classes annotated with {@link Public}.
*/
This seems to indicate that these classes can be changed even within a
patch version of Flink, though the statement "might be changed across
versions" is a bit ambiguous in this regard.
Is my statement correct? I'm wondering how important it is to preserve the
API in classes annotated like this. For example, would it be considered
appropriate to modify an interface if not doing so would require
introducing a second version of the interface to support a new feature?
This relates specifically to this change
https://github.com/apache/flink/pull/19417
Thank you
Re: Usage of PublicEvolving annotation
Hi Blake,
thank you for reaching out. @PublicEvolving interface can only be changed
with a minor release of Apache Flink (e.g. 1.6). While the JavaDoc is
indeed ambiguous there was a FLIP recently that discussed this topic:
https://cwiki.apache.org/confluence/display/FLINK/FLIP-196%3A+Source+API+stability+guarantees
If you have time, feel free to open a PR to align the JavaDocs. Happy to
merge that.
Cheers,
Konstantin
Am So., 10. Juli 2022 um 07:07 Uhr schrieb Blake Wilson <
bl...@yellowpapersun.com>:
> Hello,
> I've noticed the usage of "PublicEvolving" in some Flink classes described
> as follows
>
> /**
> * Annotation to mark classes and methods for public use, but with evolving
> interfaces.
> *
> * Classes and methods with this annotation are intended for public use
> and have stable behavior.
> * However, their interfaces and signatures are not considered to be stable
> and might be changed
> * across versions.
> *
> * This annotation also excludes methods and classes with evolving
> interfaces / signatures within
> * classes annotated with {@link Public}.
> */
>
> This seems to indicate that these classes can be changed even within a
> patch version of Flink, though the statement "might be changed across
> versions" is a bit ambiguous in this regard.
>
> Is my statement correct? I'm wondering how important it is to preserve the
> API in classes annotated like this. For example, would it be considered
> appropriate to modify an interface if not doing so would require
> introducing a second version of the interface to support a new feature?
>
> This relates specifically to this change
> https://github.com/apache/flink/pull/19417
>
> Thank you
>
--
https://twitter.com/snntrable
https://github.com/knaufk
Usage of PublicEvolving annotation
Hello,
I've noticed the usage of "PublicEvolving" in some Flink classes described
as follows
/**
* Annotation to mark classes and methods for public use, but with evolving
interfaces.
*
* Classes and methods with this annotation are intended for public use
and have stable behavior.
* However, their interfaces and signatures are not considered to be stable
and might be changed
* across versions.
*
* This annotation also excludes methods and classes with evolving
interfaces / signatures within
* classes annotated with {@link Public}.
*/
This seems to indicate that these classes can be changed even within a
patch version of Flink, though the statement "might be changed across
versions" is a bit ambiguous in this regard.
Is my statement correct? I'm wondering how important it is to preserve the
API in classes annotated like this. For example, would it be considered
appropriate to modify an interface if not doing so would require
introducing a second version of the interface to support a new feature?
This relates specifically to this change
https://github.com/apache/flink/pull/19417
Thank you
