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://hadoop.apache.org/docs/r2.7.1/api/org/apache/hadoop/classification/InterfaceStability.html
In Hadoop, InterfaceStability is paired with @InterfaceAudience
(Public / LimitedPrivate / Private), which is a richer model than a
single @PublicApi marker:
https://hadoop.apache.org/docs/r2.7.1/api/org/apache/hadoop/classification/InterfaceAudience.html
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
