flink-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Vasiliki Kalavri <vasilikikala...@gmail.com>
Subject Re: Tagging Flink classes with InterfaceAudience and InterfaceStability
Date Tue, 10 Nov 2015 19:39:04 GMT
Hi Robert,

thanks for bringing this up!

I generally like the idea, but I wouldn't rush to annotate the Gelly
classes yet. Gelly hasn't had that many users and I'm quite sure we'll find
things to improve as it gets more exposure.
TBH, I think it's quite unfair to force Gelly (also e.g. ML, Table) to a
"1.0" status (from an API stability point of view) since they're really
young compared to the other Flink APIs.

Cheers,
Vasia.
On Nov 10, 2015 8:04 PM, "Robert Metzger" <rmetzger@apache.org> wrote:

> 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