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