Hello Folks, I am reviving this thread since I did not receive any votes in the voting thread - https://lists.apache.org/thread/9wwrx3m7s5k05hxkqd4ygdfpv0n50f0r . I request everyone to please share your feedback on how I can improve the KIP, so that I can get more engagement in the voting thread. I believe that I have incorporated all the feedback which I have received so far.
Cheers, Ashwin On Fri, Jan 23, 2026 at 8:46 AM Ashwin <[email protected]> wrote: > 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 >>> > >> >>> > > >>> > >>> >>
