Hi Robert, Thanks a lot for all the work of going through the classes. At first sight, the classes look quite well chosen.
One question concerning the @Public, @Experimental, and @Internal annotations: @Public may only be used for classes or interfaces. @Experimental or @Internal are used for marking methods in @Public classes only? If that is the case, we should restrict the annotations to this scope via @Target. The current master also permits to tag classes with @Experimental or @Internal. Marking classes with @Experimental might actually make sense. What was the rational behind always declaring a class public first to restrict its methods to internal or experimental? Cheers, Max On Fri, Feb 5, 2016 at 3:07 PM, Robert Metzger <rmetz...@apache.org> wrote: > Hi, > > tl;dr: we now have @Public, @Internal, @Experimental annotations. Check > your stuff before the release! > > Fabian and I spend some time the last weeks to annotate all classes we > consider to be userfacing and stable with the "*@Public*" annotation. I > just pushed those changes to master. > > There is also an annotation "*@Internal*" for marking interfaces users > should not use because they are internal to the system (for example > "DataStream.getId()"). > > The annotation "*@Experimental*" marks unstable methods within stable > classes (for example SingleOutputStreamOperator.uid()). > Also note that we should also annotate @Deprecated methods with > @Experimental so that they are not part of the stable interface (this works > only before the 1.0 release). I checked that all current @Deprecated > annotations are excluded. > > > *I would like to ask everyone to spend some time before the 1.0 release to > go through some core classes and see if there is anything we forgot.* > *We will not be able to touch methods and classes which are public after > the 1.0 release.* > > Some areas where I feel we should check closely are the following: > - InputFormats > - State-related classes > - Windowing related classes > - DataStream API (global() / forward(); output to files; ... ). > > Fabian and I also realized that there are some downsides to this annotation > approach. > a) By not annotating all classes, its easy to forget some classes. And its > not obvious to users that "no annotation" means "not public". > > b) For example the "SourceFunction.SourceContext" interface is @Public > because users use the methods of the interface. > However, the underlying implementations are internal to Flink (users will > most likely not implement their own SourceContexts). Adding a new method to > the SourceContext interface will break its compatibilty (because users > would need to implement the new method), however, for API users it does not > matter when we are adding new methods. > We decided to make the interface @Public, but we added a comment explaining > the issue. > If we want to add a method after the 1.0 release, we can define an exclude > in the maven plugin which enforces the interface stability. > > > For making the whole annotation analysis business a bit easier, I'm > currently working on a little tool to output a list of public classes and > methods. I'll post that on the mailing list at a later point. > > Regards, > Robert
