flink-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Metzger <rmetz...@apache.org>
Subject Re: Tagging Flink classes with InterfaceAudience and InterfaceStability
Date Tue, 10 Nov 2015 19:04:36 GMT
Hi everyone,

I would like to bring this discussion back to your attention as we seem to
approach the 1.0 release of Flink.

My suggestion back in January was to annotate all classes, but I think
it'll be more feasible to just annotate public classes.
So how about adding an annotation @PublicInterface

For @PublicInterface, I would annotate classes such as: DataSet,
DataStream, ExecutionEnvironment, InputFormat, MapFunction, FileSystems but
also Gelly for example.

I would not annotate as public components such as ML, Storm compatibility,
internals from runtime, yarn, optimizer.


>From a tooling perspective, I've looked into different maven plugins and
java libraries and I found https://github.com/siom79/japicmp to be the
closest to our needs. I actually opened a pull request to the project to
allow inclusion/exclusion of classes based on annotations. Lets hope it
gets merged.

Does everybody agree with adding just the @PublicInterface annotation?

Note that I'll add the annotation on a class-level, making the entire class
either public or private (from a stability point of view). If we need a
more fine-grained annotation, we have to add a second @PrivateInterface
annotation which we'll only apply to certain methods.

The next step is that I'm going to open a pull request with all classes
annotated that I consider public.


On Fri, Jan 30, 2015 at 7:10 PM, Henry Saputra <henry.saputra@gmail.com>
wrote:

> I like the idea. But would love to have different name for the
> "LimitedPrivate" to make it easier to distinguish.
> How about "Module" or "Package" ?
>
> - Henry
>
> On Wed, Jan 28, 2015 at 1:29 AM, Robert Metzger <rmetzger@apache.org>
> wrote:
> > I think in Hadoop they use LimitedPrivate for the different components of
> > the project.
> > For example LimitedPrivate("yarn").
> > Here is a very good documentation on the topic:
> >
> https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/InterfaceClassification.html
> >
> > On Tue, Jan 27, 2015 at 3:58 PM, Alexander Alexandrov <
> > alexander.s.alexandrov@gmail.com> wrote:
> >
> >> I don't get the difference between Private and LimitedPrivate, but
> >> otherwise seems like quite a nice idea.
> >>
> >> It will be also good if we can agree upon what these tags actually mean
> and
> >> add this meaning to the documentation.
> >>
> >> 2015-01-27 15:46 GMT+01:00 Robert Metzger <rmetzger@apache.org>:
> >>
> >> > Hi,
> >> >
> >> > Hadoop has annotations for tagging the stability and audience of
> classes
> >> > and methods.
> >> >
> >> > Through that, you can have @InterfaceAudience.Public, Private,
> >> > LimitedPrivate
> >> > and also @InterfaceStability.Evolving, Unstable, and Stable.
> >> >
> >> > I guess there are tools which allow to automatically check if
> interfaces,
> >> > which are marked as Stable have been changed between releases (or by
> pull
> >> > requests).
> >> >
> >> > I think such annotations are crucial if we want to guarantee interface
> >> > stability between releases.
> >> >
> >> > What do you think? Should we add those annotations? Which one would
> you
> >> > like to add?
> >> >
> >> >
> >> > Robert
> >> >
> >>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message