For what it's worth, the new Apache Yetus [0] project includes an interface audience annotations module [1]. We have (or intend to have, if it's not available yet) tools for validation of public API compatibility across release versions. For example, here's such a report [2] from a previous HBase RC vote thread.
"Intend to have", as we have this already in Hadoop and HBase; Yetus is an effort to extract many of the software engineering tools that have developed in and around Hadoop Ecosystem of tools into their own TLP. [0]: http://yetus.apache.org/ [1]: https://github.com/apache/yetus/tree/master/audience-annotations-component [2]: http://people.apache.org/~ndimiduk/1.1.0_1.1.2RC2_compat_report.html On Tue, Nov 10, 2015 at 11:04 AM, 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 > > >> > > > >> > > >
