viktorsomogyi commented on code in PR #22470:
URL: https://github.com/apache/kafka/pull/22470#discussion_r3356554883
##########
AGENTS.md:
##########
@@ -0,0 +1,127 @@
+# 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` 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
Review Comment:
nit: Missing trailing `|`
##########
AGENTS.md:
##########
@@ -0,0 +1,127 @@
+# 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` and `streams`; 17+ for other modules.
Review Comment:
Should we add generator too to this list? Although it may not be frequently
contributed to, it's a top level component too.
##########
AGENTS.md:
##########
@@ -0,0 +1,127 @@
+# 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` 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
Review Comment:
We could add commit conventions that we use. The agents should start their
commits with KAFKA-XXXXX or MINOR and should reference a valid Jira ticket.
We could also mention that [some
packages](https://github.com/apache/kafka/blob/d559af58d8d0be113b6a96b6367a21b3e4d04197/build.gradle#L2126)
contain public interfaces and modifying them or any protocol / config / metric
generally require a KIP.
--
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]
