AndrewJSchofield commented on code in PR #22470:
URL: https://github.com/apache/kafka/pull/22470#discussion_r3379197385
##########
AGENTS.md:
##########
@@ -0,0 +1,130 @@
+# Apache Kafka — Agent Guide
+
+This file provides guidance for AI coding agents working with the Apache Kafka
codebase.
+For human contributors, see [README.md](README.md) and
[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Project overview
+
+Apache Kafka is a distributed event streaming platform. This repo is a
**Gradle**
+build in **Java** and **Scala 2.13**.
+
+- **Supported JDK**: 11+ for `clients`, `generator`, and `streams`; 17+ for
other modules.
+- **Build/test JDK**: Java 17 and 25.
+- **Build tool**: Gradle, wrapper `./gradlew` is recommended.
+
+## Repository layout (high level)
+
+| Path | Purpose
|
+|------|--------------------------------------------------------------------------------------|
+| `clients/` | Producer, consumer, admin client APIs and protocol messages
|
+| `core/` | Broker runtime, log, replication, request handling
|
+| `server/`, `server-common/` | Broker/server components and shared server
code |
+| `metadata/`, `raft/` | KRaft metadata layer and Raft implementation
|
+| `storage/`, `storage/api/` | Log segments, checkpoints, tiered storage APIs
|
+| `group-coordinator/`, `share-coordinator/`, `transaction-coordinator/` |
Coordinators
|
+| `connect/` | Kafka Connect (api, runtime, plugins, transforms)
|
+| `streams/` | Kafka Streams (+ Scala, examples, upgrade system tests)
|
+| `generator/` | RPC/message code generation
|
+| `tools/`, `shell/` | CLI tools and kafka metadata shell
|
+| `examples/` | Kafka producer and consumer examples
|
+| `jmh-benchmarks/` | Kafka benchmarks tests
|
+| `trogdor/` | test framework
|
+| `tests/` | System test harness (see `tests/README.md`)
|
+| `config/` | Sample broker/controller configuration |
+| `checkstyle/` | Checkstyle rules and import-control XML
|
+| `docs/` | Documentation sources
|
+
+
+## Build commands
+
+```bash
+# Compile jars
+./gradlew jar
+
+# Release tarball (output under core/build/distributions/)
+./gradlew clean releaseTarGz
+
+# Publish to local Maven (skip signing for local dev)
+./gradlew -PskipSigning=true publishToMavenLocal
+
+# Regenerate RPC/message classes after branch switches
+./gradlew processMessages processTestMessages
+
+# List tasks
+./gradlew tasks
+```
+
+Module-scoped build:
+
+```bash
+./gradlew core:jar
+./gradlew clients:jar
+./gradlew :streams:testAll
+```
+
+## Test commands
+
+```bash
+# All unit + integration tests
+./gradlew test
+
+# Split suites
+./gradlew unitTest
+./gradlew integrationTest
+
+# Include flaky tests (marked @Flaky)
+./gradlew test -Pkafka.test.run.flaky=true
+
+# Re-run without considering up-to-date
+./gradlew test --rerun-tasks
+
+# Single test class
+./gradlew clients:test --tests RequestResponseTest
+
+# Single test method
+./gradlew core:test --tests
kafka.api.ProducerFailureHandlingTest.testCannotSendToInternalTopic
+
+# Coverage (whole project or one module)
+./gradlew reportCoverage -PenableTestCoverage=true -Dorg.gradle.parallel=false
+./gradlew clients:reportCoverage -PenableTestCoverage=true
-Dorg.gradle.parallel=false
+```
+
+**Test retries** (optional): `-PmaxTestRetries=1 -PmaxTestRetryFailures=3`
+
+**Logging**: adjust `log4j2.yaml` under `<module>/src/test/resources/` for
verbose test logs.
+
+**System tests**: see [tests/README.md](tests/README.md).
+
+## Code quality
+
+Run before submitting Java changes:
+
+```bash
+./gradlew spotlessApply # fix import order / formatting
+./gradlew checkstyleMain checkstyleTest spotlessCheck
+./gradlew spotbugsMain spotbugsTest -x test # optional static analysis
+```
+
+Checkstyle reports: `<module>/build/reports/checkstyle/`.
+
+## Coding conventions
+
+- **Commits / PR titles**: Start with `KAFKA-XXXXX`, `MINOR`, or `HOTFIX`. Use
`KAFKA-XXXXX` only when there is a valid Jira ticket for the change.
+- **AI-generated contributions**: Follow the [AI-Generated
Contributions](CONTRIBUTING.md#ai-generated-contributions) section in
`CONTRIBUTING.md` — add a `Co-Authored-By` or `Generated-by` commit trailer for
AI-assisted changes.
+- **Public API / KIP**: Changes to public client interfaces, wire protocol,
broker configuration, or metrics generally require a
[KIP](https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Improvement+Proposals).
See the `javadoc` `include` list in [build.gradle](build.gradle) for packages
treated as public API.
Review Comment:
I think all configurations generally require a KIP (broker, client, group,
topic).
##########
AGENTS.md:
##########
@@ -0,0 +1,130 @@
+# Apache Kafka — Agent Guide
+
+This file provides guidance for AI coding agents working with the Apache Kafka
codebase.
+For human contributors, see [README.md](README.md) and
[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Project overview
+
+Apache Kafka is a distributed event streaming platform. This repo is a
**Gradle**
+build in **Java** and **Scala 2.13**.
+
+- **Supported JDK**: 11+ for `clients`, `generator`, and `streams`; 17+ for
other modules.
+- **Build/test JDK**: Java 17 and 25.
+- **Build tool**: Gradle, wrapper `./gradlew` is recommended.
+
+## Repository layout (high level)
+
+| Path | Purpose
|
+|------|--------------------------------------------------------------------------------------|
+| `clients/` | Producer, consumer, admin client APIs and protocol messages
|
+| `core/` | Broker runtime, log, replication, request handling
|
+| `server/`, `server-common/` | Broker/server components and shared server
code |
+| `metadata/`, `raft/` | KRaft metadata layer and Raft implementation
|
+| `storage/`, `storage/api/` | Log segments, checkpoints, tiered storage APIs
|
+| `group-coordinator/`, `share-coordinator/`, `transaction-coordinator/` |
Coordinators
|
+| `connect/` | Kafka Connect (api, runtime, plugins, transforms)
|
+| `streams/` | Kafka Streams (+ Scala, examples, upgrade system tests)
|
+| `generator/` | RPC/message code generation
|
+| `tools/`, `shell/` | CLI tools and kafka metadata shell
|
+| `examples/` | Kafka producer and consumer examples
|
+| `jmh-benchmarks/` | Kafka benchmarks tests
|
+| `trogdor/` | test framework
|
+| `tests/` | System test harness (see `tests/README.md`)
|
+| `config/` | Sample broker/controller configuration |
+| `checkstyle/` | Checkstyle rules and import-control XML
|
+| `docs/` | Documentation sources
|
+
+
+## Build commands
+
+```bash
+# Compile jars
+./gradlew jar
+
+# Release tarball (output under core/build/distributions/)
+./gradlew clean releaseTarGz
+
+# Publish to local Maven (skip signing for local dev)
+./gradlew -PskipSigning=true publishToMavenLocal
+
+# Regenerate RPC/message classes after branch switches
+./gradlew processMessages processTestMessages
+
+# List tasks
+./gradlew tasks
+```
+
+Module-scoped build:
+
+```bash
+./gradlew core:jar
+./gradlew clients:jar
+./gradlew :streams:testAll
+```
+
+## Test commands
+
+```bash
+# All unit + integration tests
+./gradlew test
+
+# Split suites
+./gradlew unitTest
+./gradlew integrationTest
+
+# Include flaky tests (marked @Flaky)
+./gradlew test -Pkafka.test.run.flaky=true
+
+# Re-run without considering up-to-date
+./gradlew test --rerun-tasks
+
+# Single test class
+./gradlew clients:test --tests RequestResponseTest
+
+# Single test method
+./gradlew core:test --tests
kafka.api.ProducerFailureHandlingTest.testCannotSendToInternalTopic
+
+# Coverage (whole project or one module)
+./gradlew reportCoverage -PenableTestCoverage=true -Dorg.gradle.parallel=false
+./gradlew clients:reportCoverage -PenableTestCoverage=true
-Dorg.gradle.parallel=false
+```
+
+**Test retries** (optional): `-PmaxTestRetries=1 -PmaxTestRetryFailures=3`
+
+**Logging**: adjust `log4j2.yaml` under `<module>/src/test/resources/` for
verbose test logs.
+
+**System tests**: see [tests/README.md](tests/README.md).
+
+## Code quality
+
+Run before submitting Java changes:
+
+```bash
+./gradlew spotlessApply # fix import order / formatting
+./gradlew checkstyleMain checkstyleTest spotlessCheck
+./gradlew spotbugsMain spotbugsTest -x test # optional static analysis
+```
+
+Checkstyle reports: `<module>/build/reports/checkstyle/`.
+
+## Coding conventions
+
+- **Commits / PR titles**: Start with `KAFKA-XXXXX`, `MINOR`, or `HOTFIX`. Use
`KAFKA-XXXXX` only when there is a valid Jira ticket for the change.
+- **AI-generated contributions**: Follow the [AI-Generated
Contributions](CONTRIBUTING.md#ai-generated-contributions) section in
`CONTRIBUTING.md` — add a `Co-Authored-By` or `Generated-by` commit trailer for
AI-assisted changes.
+- **Public API / KIP**: Changes to public client interfaces, wire protocol,
broker configuration, or metrics generally require a
[KIP](https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Improvement+Proposals).
See the `javadoc` `include` list in [build.gradle](build.gradle) for packages
treated as public API.
+- **License header**: New source files need the standard ASF license header
(see existing files in the same module).
+- **Checkstyle**: Enforced on main and test sources; rules in `checkstyle/`.
Import order is checked via Spotless.
+- **Generated code**: Do not hand-edit generated RPC/message sources.
Regenerate with `processMessages` / `processTestMessages`. See
[clients/src/main/resources/common/message/README.md](clients/src/main/resources/common/message/README.md).
+- **Scope**: Prefer targeted unit tests in the module you change;
integration/system tests for cross-component behavior.
+- **Compatibility**: Client and Streams modules target older Java bytecode;
avoid APIs that break those release levels.
Review Comment:
I think it is appropriate to state the Java versions which are supported
here.
##########
AGENTS.md:
##########
@@ -0,0 +1,130 @@
+# Apache Kafka — Agent Guide
+
+This file provides guidance for AI coding agents working with the Apache Kafka
codebase.
+For human contributors, see [README.md](README.md) and
[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Project overview
+
+Apache Kafka is a distributed event streaming platform. This repo is a
**Gradle**
+build in **Java** and **Scala 2.13**.
+
+- **Supported JDK**: 11+ for `clients`, `generator`, and `streams`; 17+ for
other modules.
+- **Build/test JDK**: Java 17 and 25.
+- **Build tool**: Gradle, wrapper `./gradlew` is recommended.
+
+## Repository layout (high level)
+
+| Path | Purpose
|
+|------|--------------------------------------------------------------------------------------|
+| `clients/` | Producer, consumer, admin client APIs and protocol messages
|
+| `core/` | Broker runtime, log, replication, request handling
|
+| `server/`, `server-common/` | Broker/server components and shared server
code |
+| `metadata/`, `raft/` | KRaft metadata layer and Raft implementation
|
+| `storage/`, `storage/api/` | Log segments, checkpoints, tiered storage APIs
|
+| `group-coordinator/`, `share-coordinator/`, `transaction-coordinator/` |
Coordinators
|
Review Comment:
coordinator-common too.
##########
AGENTS.md:
##########
@@ -0,0 +1,130 @@
+# Apache Kafka — Agent Guide
+
+This file provides guidance for AI coding agents working with the Apache Kafka
codebase.
+For human contributors, see [README.md](README.md) and
[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Project overview
+
+Apache Kafka is a distributed event streaming platform. This repo is a
**Gradle**
+build in **Java** and **Scala 2.13**.
+
+- **Supported JDK**: 11+ for `clients`, `generator`, and `streams`; 17+ for
other modules.
+- **Build/test JDK**: Java 17 and 25.
+- **Build tool**: Gradle, wrapper `./gradlew` is recommended.
+
+## Repository layout (high level)
+
+| Path | Purpose
|
+|------|--------------------------------------------------------------------------------------|
+| `clients/` | Producer, consumer, admin client APIs and protocol messages
|
+| `core/` | Broker runtime, log, replication, request handling
|
+| `server/`, `server-common/` | Broker/server components and shared server
code |
+| `metadata/`, `raft/` | KRaft metadata layer and Raft implementation
|
+| `storage/`, `storage/api/` | Log segments, checkpoints, tiered storage APIs
|
+| `group-coordinator/`, `share-coordinator/`, `transaction-coordinator/` |
Coordinators
|
+| `connect/` | Kafka Connect (api, runtime, plugins, transforms)
|
+| `streams/` | Kafka Streams (+ Scala, examples, upgrade system tests)
|
+| `generator/` | RPC/message code generation
|
+| `tools/`, `shell/` | CLI tools and kafka metadata shell
|
+| `examples/` | Kafka producer and consumer examples
|
+| `jmh-benchmarks/` | Kafka benchmarks tests
|
+| `trogdor/` | test framework
|
+| `tests/` | System test harness (see `tests/README.md`)
|
+| `config/` | Sample broker/controller configuration |
+| `checkstyle/` | Checkstyle rules and import-control XML
|
+| `docs/` | Documentation sources
|
+
+
+## Build commands
+
+```bash
+# Compile jars
+./gradlew jar
+
+# Release tarball (output under core/build/distributions/)
+./gradlew clean releaseTarGz
+
+# Publish to local Maven (skip signing for local dev)
+./gradlew -PskipSigning=true publishToMavenLocal
+
+# Regenerate RPC/message classes after branch switches
+./gradlew processMessages processTestMessages
+
+# List tasks
+./gradlew tasks
+```
+
+Module-scoped build:
+
+```bash
+./gradlew core:jar
+./gradlew clients:jar
+./gradlew :streams:testAll
+```
+
+## Test commands
+
+```bash
+# All unit + integration tests
+./gradlew test
+
+# Split suites
+./gradlew unitTest
+./gradlew integrationTest
+
+# Include flaky tests (marked @Flaky)
+./gradlew test -Pkafka.test.run.flaky=true
+
+# Re-run without considering up-to-date
+./gradlew test --rerun-tasks
+
+# Single test class
+./gradlew clients:test --tests RequestResponseTest
+
+# Single test method
+./gradlew core:test --tests
kafka.api.ProducerFailureHandlingTest.testCannotSendToInternalTopic
+
+# Coverage (whole project or one module)
+./gradlew reportCoverage -PenableTestCoverage=true -Dorg.gradle.parallel=false
+./gradlew clients:reportCoverage -PenableTestCoverage=true
-Dorg.gradle.parallel=false
+```
+
+**Test retries** (optional): `-PmaxTestRetries=1 -PmaxTestRetryFailures=3`
+
+**Logging**: adjust `log4j2.yaml` under `<module>/src/test/resources/` for
verbose test logs.
+
+**System tests**: see [tests/README.md](tests/README.md).
+
+## Code quality
+
+Run before submitting Java changes:
+
+```bash
+./gradlew spotlessApply # fix import order / formatting
+./gradlew checkstyleMain checkstyleTest spotlessCheck
+./gradlew spotbugsMain spotbugsTest -x test # optional static analysis
+```
+
+Checkstyle reports: `<module>/build/reports/checkstyle/`.
+
+## Coding conventions
+
+- **Commits / PR titles**: Start with `KAFKA-XXXXX`, `MINOR`, or `HOTFIX`. Use
`KAFKA-XXXXX` only when there is a valid Jira ticket for the change.
+- **AI-generated contributions**: Follow the [AI-Generated
Contributions](CONTRIBUTING.md#ai-generated-contributions) section in
`CONTRIBUTING.md` — add a `Co-Authored-By` or `Generated-by` commit trailer for
AI-assisted changes.
+- **Public API / KIP**: Changes to public client interfaces, wire protocol,
broker configuration, or metrics generally require a
[KIP](https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Improvement+Proposals).
See the `javadoc` `include` list in [build.gradle](build.gradle) for packages
treated as public API.
+- **License header**: New source files need the standard ASF license header
(see existing files in the same module).
+- **Checkstyle**: Enforced on main and test sources; rules in `checkstyle/`.
Import order is checked via Spotless.
+- **Generated code**: Do not hand-edit generated RPC/message sources.
Regenerate with `processMessages` / `processTestMessages`. See
[clients/src/main/resources/common/message/README.md](clients/src/main/resources/common/message/README.md).
+- **Scope**: Prefer targeted unit tests in the module you change;
integration/system tests for cross-component behavior.
+- **Compatibility**: Client and Streams modules target older Java bytecode;
avoid APIs that break those release levels.
Review Comment:
I read this file backwards. I see that you've already included this
information. :)
##########
AGENTS.md:
##########
@@ -0,0 +1,130 @@
+# Apache Kafka — Agent Guide
+
+This file provides guidance for AI coding agents working with the Apache Kafka
codebase.
+For human contributors, see [README.md](README.md) and
[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Project overview
+
+Apache Kafka is a distributed event streaming platform. This repo is a
**Gradle**
+build in **Java** and **Scala 2.13**.
+
+- **Supported JDK**: 11+ for `clients`, `generator`, and `streams`; 17+ for
other modules.
+- **Build/test JDK**: Java 17 and 25.
+- **Build tool**: Gradle, wrapper `./gradlew` is recommended.
+
+## Repository layout (high level)
+
+| Path | Purpose
|
+|------|--------------------------------------------------------------------------------------|
+| `clients/` | Producer, consumer, admin client APIs and protocol messages
|
+| `core/` | Broker runtime, log, replication, request handling
|
Review Comment:
I would say that this module is gradually being removed, along with Scala
code.
##########
AGENTS.md:
##########
@@ -0,0 +1,130 @@
+# Apache Kafka — Agent Guide
+
+This file provides guidance for AI coding agents working with the Apache Kafka
codebase.
+For human contributors, see [README.md](README.md) and
[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Project overview
+
+Apache Kafka is a distributed event streaming platform. This repo is a
**Gradle**
+build in **Java** and **Scala 2.13**.
+
+- **Supported JDK**: 11+ for `clients`, `generator`, and `streams`; 17+ for
other modules.
+- **Build/test JDK**: Java 17 and 25.
+- **Build tool**: Gradle, wrapper `./gradlew` is recommended.
+
+## Repository layout (high level)
+
+| Path | Purpose
|
+|------|--------------------------------------------------------------------------------------|
+| `clients/` | Producer, consumer, admin client APIs and protocol messages
|
+| `core/` | Broker runtime, log, replication, request handling
|
+| `server/`, `server-common/` | Broker/server components and shared server
code |
+| `metadata/`, `raft/` | KRaft metadata layer and Raft implementation
|
+| `storage/`, `storage/api/` | Log segments, checkpoints, tiered storage APIs
|
+| `group-coordinator/`, `share-coordinator/`, `transaction-coordinator/` |
Coordinators
|
+| `connect/` | Kafka Connect (api, runtime, plugins, transforms)
|
+| `streams/` | Kafka Streams (+ Scala, examples, upgrade system tests)
|
+| `generator/` | RPC/message code generation
|
+| `tools/`, `shell/` | CLI tools and kafka metadata shell
|
+| `examples/` | Kafka producer and consumer examples
|
+| `jmh-benchmarks/` | Kafka benchmarks tests
|
+| `trogdor/` | test framework
|
+| `tests/` | System test harness (see `tests/README.md`)
|
+| `config/` | Sample broker/controller configuration |
+| `checkstyle/` | Checkstyle rules and import-control XML
|
+| `docs/` | Documentation sources
|
+
Review Comment:
And `docker/`
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
