Thanks for working on this! It's much needed, I remember many times where I'd catch similar misses in PR reviews in the last minute.
As for helping Plugin devs, how do we precisely plan to "provide a sample configuration" and "publish a sample APILyzer configuration". Do we expect people to know where to find these things from the docs and copy them to their own repos? Can you think of any ways to warn Kafka users, i.e people who import `org.apache.kafka.Something`, of the fact they're depending on an unstable API too? Best, Stan On 2026/01/08 07:21:23 Ashwin via dev wrote: > Thanks for your feedback Ismael ! I was not aware of the InterfaceStability > annotation ! > I have updated the KIP based on your suggestions > https://cwiki.apache.org/confluence/display/KAFKA/KIP-1265%3A+Mechanism+for+automatic+detection+of+internal+API+usage > and hope that all your points have been added to it. > > Team - Please do let me know your thoughts. > Thanks, > Ashwin > > On Tue, Jan 6, 2026 at 6:10 AM Ismael Juma <[email protected]> wrote: > > > Hi Ashwin, > > > > Improving how we specify public API and providing a mechanism for > > automatic detection of internal api usage would be great. That said, it's > > incorrect that there is no mechanism for that today. We should update the > > KIP to specify the current situation correctly and the problems with it. > > > > A summary of items to consider for the KIP: > > 1. As a user, the way to know the public API is to consult the project's > > published javadoc: this is a "concrete, centralized definition of what > > constitutes a public API". > > 2. As a Kafka developer, you specify it via a block like this: > > https://github.com/apache/kafka/blob/trunk/build.gradle#L2026 > > 3. There is no tooling that automatically detects if a public method > > exposes an internal class (there was a recent KIP that was introduced > > because we accidentally exposed an internal class) > > 4. There is no simple mechanism for users of Kafka to configure their > > build system so that usage of Kafka internal apis are flagged. > > 5. There are already annotations to specify whether a class or method is > > stable, evolving or unstable: > > https://github.com/apache/kafka/blob/trunk/clients/src/main/java/org/apache/kafka/common/annotation/InterfaceStability.java > > > > Thanks, > > Ismael > > > > On Sun, Jan 4, 2026 at 8:21 PM Ashwin via dev <[email protected]> > > wrote: > > > >> Hello folks, > >> > >> Reviving this old thread > >> https://lists.apache.org/thread/ly5ddkobr1wc07gvhwc1p0jg94qg8cxc to > >> discuss > >> KIP-1265. > >> > >> Apache Kafka lacks a concrete, centralized definition of what constitutes > >> a > >> public API. The most relevant information currently available is found > >> here: > >> > >> Kafka Improvement > >> Proposals#Whatisconsidereda%22majorchange%22thatneedsaKIP > >> < > >> https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Improvement+Proposals#KafkaImprovementProposals-Whatisconsidereda%22majorchange%22thatneedsaKIP > >> > > >> > >> Without formal definition or guardrails, there is a risk that builders may > >> inadvertently import internal classes leading to possible build breakages > >> when they compile against a newer Kafka version > >> > >> > >> Please let me know your thoughts for > >> > >> https://cwiki.apache.org/confluence/display/KAFKA/KIP-1265%3A+Public+API+needs+to+be+explicitly+declared > >> > >> Cheers, > >> Ashwin > >> > > >
