Hello folks, I have created a draft PR to demonstrate the changes involved: https://github.com/apache/kafka/pull/21337/files .
In this PR, I have annotated the KafkaProducer class with @PublicApi. Any " un-annotated" classes present in the Javadoc jar will be reported, causing the final docsJar step to fail. This public API checker will also check the public methods, args and exception types - to avoid unintentional exposure of internal classes. For the plugin developer's reference, I have created a test repository using the new Gradle and Maven checkers: - Gradle: https://github.com/ashwinpankaj/kip1265test/blob/58d4f88f54d8324fb76656f24ad4334e483cdd55/gradle-test/my-simple-app/build.gradle#L60-L64 - Maven: https://github.com/ashwinpankaj/kip1265test/blob/58d4f88f54d8324fb76656f24ad4334e483cdd55/maven-test/my-simple-app/pom.xml#L44-L71 Both builds in this repository pass for KafkaProducer but fail for other imports from org.apache.kafka.*. Please let me know your thoughts, as I plan to start the vote for this KIP next week. Thanks, Ashwin On Tue, Jan 20, 2026 at 6:52 PM Ashwin <[email protected]> wrote: > Thanks for providing feedback Stan ! Sorry I couldn't reply earlier . > > I too was having second thoughts about Plugin development support which I > proposed earlier . I now feel that we should publish Gradle and Maven > plugins from Apache Kafka. Developers can then use these plugins in their > build config. > > I have published the proposal at > https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=406618601#KIP1265:MechanismforautomaticdetectionofinternalAPIusage-GuardrailsforPlugindevelopers > . > > Please have a look and let me know what you think. > > Cheers, > Ashwin > > On Wed, Jan 14, 2026 at 1:53 AM Stanislav Kozlovski < > [email protected]> wrote: > >> 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 >> > >> >> > > >> > >> >
