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
