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" <rmetz...@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.sapu...@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 <rmetz...@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.alexand...@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 <rmetz...@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 > > >> > > > >> > > >
