Hi Manikumar, Thank you so much for reviewing the KIP.
1. I get your point regarding InterfaceAudience (we had earlier discussed this in the thread , there were no strong opinions for or against it). I have updated the KIP with this new annotation. I have not added LimitedPrivate - as I don't think we can use it to enforce checks for Plugin developers (I have mentioned this in the KIP) 2. That is a great point ! I have updated the KIP with this approach. 3. Fair point - updated in the KIP 4. Agreed. Cheers, Ashwin On Tue, May 12, 2026 at 4:24 PM Manikumar <[email protected]> wrote: > Hi Ashwin, > > Thanks for working on this. A few questions/suggestions: > > 1. Relationship with the existing InterfaceStability annotation. We > already have @InterfaceStability.{Stable,Evolving,Unstable} applied > across the codebase, > and it looks like Kafka's InterfaceStability was originally borrowed > from Hadoop's @InterfaceStability: > > https://urldefense.com/v3/__https://hadoop.apache.org/docs/r2.7.1/api/org/apache/hadoop/classification/InterfaceStability.html__;!!Ayb5sqE7!rDuqH6O-GV8sRTDtC9qrhH1DSsZ7-VSm479gcYux9CAW_qzLfPH1m8rCD1s44MZysaKCJJ18aySHVzYbNGtcTwW3k68T$ > > In Hadoop, InterfaceStability is paired with @InterfaceAudience > (Public / LimitedPrivate / Private), which is a richer model than a > single @PublicApi marker: > > https://urldefense.com/v3/__https://hadoop.apache.org/docs/r2.7.1/api/org/apache/hadoop/classification/InterfaceAudience.html__;!!Ayb5sqE7!rDuqH6O-GV8sRTDtC9qrhH1DSsZ7-VSm479gcYux9CAW_qzLfPH1m8rCD1s44MZysaKCJJ18aySHVzYbNGtcTzz1tYf2$ > > Could we consider borrowing @InterfaceAudience as well, instead of > introducing a separate @PublicApi marker? That would let us: > - Cleanly distinguish "public to end users" vs "public to > connector/plugin developers only" vs "internal" > - Keep the audience and stability dimensions orthogonal, matching > what Hadoop has proven works > - Avoid the ambiguity of how @PublicApi interacts with > @InterfaceStability.Evolving > > If we go with a new @PublicApi instead, could the KIP explicitly say > how it relates to @InterfaceStability (replace it, coexist with it, > etc.)? > > 2. External check robustness. The external-usage check regex-scans > .java source files for imports. This misses Scala/Kotlin consumers and > fully-qualified usages. Have you considered an ASM-based bytecode scan > instead? That would catch all JVM-language consumers uniformly. > > 3. Suppression mechanism. Is there a way to mark a known/intentional > violation? Without one, the checker can't be turned on in projects > that already have legitimate exposures. > > 4. I would suggest making the annotation @Documented so it surfaces > in javadoc, and adding a since attribute. > > Thanks, > Manikumar >
