flink-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stephan Ewen <se...@apache.org>
Subject Re: Tagging Flink classes with InterfaceAudience and InterfaceStability
Date Tue, 10 Nov 2015 21:24:01 GMT
I think we need anyways an annotation "@PublicExperimental".

We can make this annotation such that it can be added to methods and can
use that to declare
Methods in an otherwise public class (such as DataSet) as experimental.

On Tue, Nov 10, 2015 at 10:19 PM, Fabian Hueske <fhueske@gmail.com> wrote:

> I am not sure if we always should declare complete classes as
> @PublicInterface.
> This does definitely make sense for interfaces and abstract classes such as
> MapFunction or InputFormat but not necessarily for classes such as DataSet
> that we might want to extend by methods which should not immediately be
> considered as stable.
>
>
> 2015-11-10 21:36 GMT+01:00 Vasiliki Kalavri <vasilikikalavri@gmail.com>:
>
> > Yes, my opinion is that we shouldn't declare the Gelly API frozen yet.
> > We can reconsider when we're closer to the 1.0 release, but if possible,
> I
> > would give it some more time.
> >
> > -V.
> >
> > On 10 November 2015 at 21:06, Stephan Ewen <sewen@apache.org> wrote:
> >
> > > 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
> > > > > > >> >
> > > > > > >>
> > > > > >
> > > > >
> > > >
> > >
> >
>

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