Hi devs, While I was joining the flink-avro enhancement and cleanup discussion driven by Becket[1], I realized that there are some issues with the current Flink API annotation usage in the source code.
As far as I am concerned, Flink wants to control the access/visibility of APIs across modules and for downstreams. Since no OSGI is used(it should not be used because of its complexity, IMHO), Flink decided to use a very lightweight but manual solution: customized annotation like @Internal, @Experimental, @PublicEvolving, etc. This is a Flink only concept on top of JDK annotation and is therefore orthogonal to @Deprecated or any other annotations offered by JDK. After this concept has been used, APIs without one of these annotations are in the kind of gray area which means they have no contract in the context of this new concept. Without any given metadata they could be considered as @Internal or @Experimental, because changes are allowed to be applied at any time. But there is no clear definition and therefore different people will understand it differently. There are two options to improve it, as far as I could figure out: option 1: All APIs must have one of those annotations. We should put some effort into going through all source code and add missing annotations. There were discussions[2] and activities going in this direction. option 2: the community comes to a new consensus that APIs without annotation equals one of @Internal, @Experimental, or @PublicEvolving. I personally will choose @Internal, because it is the safest one. And if @Internal is chosen as the default one, it could also be deprecated, because no annotation equals @Internal. If it makes sense, I can create a FLIP and help the community reach this consensus. Both options have their own pros and cons. I would choose option 2, since we will not end up with a lot of APIs marked as @Internal. Looking forward to hearing your thoughts. Best regards Jing [1] https://lists.apache.org/thread/7zsv528swbjxo5zk0bxq33hrkvd77d6f [2] https://lists.apache.org/thread/zl2rmodsjsdb49tt4hn6wv3gdwo0m31o
