Mailing-List: contact dev-help@flink.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@flink.apache.org
MIME-Version: 1.0
Sender: ewenstephan@gmail.com
In-Reply-To: 
 <CAJZ2dcU7OwAePP0rTdGULn08+y6wcwGvteNKOOC2p1_NKSGw1g@mail.gmail.com>
References: 
 <CAGr9p8AOzLQ041WxRbWj=ZpaH2Sn5mAYR+U6stHq8OCfYkXmAQ@mail.gmail.com>
	<CAEXqXcbsAh9cVKGms_j1Zp+XKUt84+RtR2FGAyFTE7qpKomViw@mail.gmail.com>
	<CAGr9p8BR3nNF5ysTUEBqvRAjzZXVuPVqBTrF5LYqo=mXREromw@mail.gmail.com>
	<CALuGr6ZA5pmA3gUC7B_aZPtpxm-K76SL1WkWL+hFgbg4KT0t9w@mail.gmail.com>
	<CAGr9p8BAEQvz3HNndjwytB4v4QsOktpgJ+rkJEJp_s98FCuY7g@mail.gmail.com>
	<CAJZ2dcU7OwAePP0rTdGULn08+y6wcwGvteNKOOC2p1_NKSGw1g@mail.gmail.com>
Date: Tue, 10 Nov 2015 21:06:55 +0100
Message-ID: 
 <CANC1h_to3T-w4O0a7m=7Wv2bVZ0pekxEoz--n=qQJcWLb+r_Vw@mail.gmail.com>
Subject: Re: Tagging Flink classes with InterfaceAudience and
 InterfaceStability
From: Stephan Ewen <sewen@apache.org>
To: "dev@flink.apache.org" <dev@flink.apache.org>
Content-Type: multipart/alternative; boundary=001a1135636c660260052435403d

--001a1135636c660260052435403d
Content-Type: text/plain; charset=UTF-8

I think no component should be forced to be stable. It should be an
individual decision for each component, and in some cases even for
individual classes.

@Vasia If you think Gelly should not be declared interface-frozen, then
this is a good point to raise and this should definitely be reflected.
There is no point in declaring certain APIs as frozen when we are not yet
confident they have converged.


On Tue, Nov 10, 2015 at 8:39 PM, Vasiliki Kalavri <vasilikikalavri@gmail.com
> wrote:

> 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
> > > >> >
> > > >>
> > >
> >
>

--001a1135636c660260052435403d--