Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-10 Thread Till Rohrmann
Thanks a lot for all your input. I hope that I could resolve most of your concerns. I will now start a vote on this FLIP. Cheers, Till On Tue, Dec 7, 2021 at 4:28 PM Till Rohrmann wrote: > Hi Fabian, > > Thanks for your input. Adding the definition of the different labels to > our documentation

Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-07 Thread Till Rohrmann
Hi Fabian, Thanks for your input. Adding the definition of the different labels to our documentation is definitely part of this FLIP. I agree that deprecation is related to API stability. For the sake of keeping this FLIP narrowly scoped I left it out, though. For the time being I suggest that we

Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-07 Thread Fabian Paul
Hi all, Thanks Till for starting this discussion. It is great to see these facts written down since they definitely caused friction in the past because of different interpretations. Overall I agree with everything being said in this FLIP. I was just wondering whether we can put the label explainin

Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-06 Thread Ingo Bürk
Hi Till, seems I misunderstood it then; thanks for the clarification! And yes, with that I would fully agree. Ingo On Mon, Dec 6, 2021 at 9:59 AM Till Rohrmann wrote: > Hi Ingo, > > No, the added method can have a weaker stability guarantee as long as the > user does not have to implement it.

Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-06 Thread Till Rohrmann
Hi Ingo, No, the added method can have a weaker stability guarantee as long as the user does not have to implement it. In order to give an example the following extension would be ok imo: @Public interface Foobar { @Public int foo(); @Experimental default ExperimentalResult bar()

Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-03 Thread Ingo Bürk
> Would it be enough to say that for example all classes in the module flink-java have to be annotated? What I would like to avoid is having to annotate all classes in some internal module like flink-rpc. I don't think it is, but we certainly could restrict it to certain top level o.a.f.xyz packag

Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-03 Thread Till Rohrmann
>That's still a much weaker requirement, though, as classes can just be left unannotated, which is why I prefer annotating all classes regardless of location. Would it be enough to say that for example all classes in the module flink-java have to be annotated? What I would like to avoid is having

Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-03 Thread Ingo Bürk
Hi Till, > Personally, I'd be fine to say that in API modules (tbd what this is > (probably transitive closure of all APIs)) we require every class to be > annotated. At least we'll then need the reverse rule: no classes outside *.api.* packages CAN have an API annotation (other than Internal), o

Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-03 Thread Till Rohrmann
Hi Ingo, thanks a lot for your thoughts and the work you've spent on this topic already. Personally, I'd be fine to say that in API modules (tbd what this is (probably transitive closure of all APIs)) we require every class to be annotated. For sake of clarity and having clear rules, this should

Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-03 Thread Ingo Bürk
Hi Till, Thanks for starting this discussion, and as you noticed, I qutie care for it as well. :-) When implementing the ArchUnit rules, I noticed that project-wide, different teams / modules use and understand the API annotations in different ways. Therefore, I think it is important to both get

Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-03 Thread Till Rohrmann
Fyi: Ingo already implemented most of the FLIP by introducing the ApiAnnotationRules.PUBLIC_API_METHODS_USE_ONLY_PUBLIC_API_TYPES and .PUBLIC_EVOLVING_API_METHODS_USE_ONLY_PUBLIC_EVOLVING_API_TYPES [1] using ArchUnit :-) [1] https://github.com/apache/flink/blob/master/flink-architecture-tests/src/

Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-03 Thread Till Rohrmann
Hi Konstantin and Francesco, > * Are you planning to implement the required tests via ArchUnit? If ArchUnit is the best tool for the job, then I will probably use it. But I haven't investigated it yet. > * Fixing existing "test failures" is in the scope of this FLIP, correct? Yes I think that f

Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-03 Thread Francesco Guardiani
Hi Till, Thanks for starting this discussion, I think it's very beneficial for the community to have stable APIs, in particular to develop connectors and formats. A couple of comments: > I would suggest that we document these guarantees prominently under /docs/dev/api_stability. I think it woul

Re: [DISCUSS] FLIP-196: Source API stability guarantees

2021-12-03 Thread Konstantin Knauf
Hi Till, Thank you for picking up this topic. Explicit and consistent stability guarantees are important for our users as well as any downstream project of Apache Flink. Documenting the de-facto status quo and tackling existing inconsistencies sounds like a good first step. So, +1 from my side. T