mirrors/kafka
0
0 Fork 0
mirror of https://github.com/apache/kafka.git synced 2026-10-28 08:24:58 +08:00
Code Activity

MINOR: adding AGENTS.md (#22470)

Browse Source 
Added `AGENTS.md`.

Co-Authored-By: Claude Sonnet 4.6 <claude@anthropic.com>

Reviewers: Viktor Somogyi-Vass <viktorsomogyi@gmail.com>, Andrew
 Schofield <aschofield@confluent.io>

---------

Co-authored-by: Claude Sonnet 4.6 <claude@anthropic.com>
This commit is contained in:
Luke ChenandClaude Sonnet 4.6 authored and GitHub committed 2026-06-18 18:50:51 +09:00
1 parent 5b70498523
commit ca0c503be9
3 files changed
+149 -1
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

AGENTS.md
+129 -1
View File
@@ -20,6 +20,122 @@
This file is read by automated agents (security scanners, code analyzers,
AI assistants) operating on this repository.
## 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 (gradually being removed along with Scala code) |
| `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/`, `coordinator-common/` | 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 |
| `docker/` | Docker images, build/test scripts, and examples for JVM and native Kafka |
## 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 interfaces, wire protocol, configurations, 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**: clients, generator, and streams modules support Java 11+; all other modules require Java 17+. Avoid APIs that break those release levels.
## Security
See [SECURITY.md](./SECURITY.md) for how to report a vulnerability and for links
@@ -28,4 +144,16 @@ to the Apache Kafka security model under [docs/security/](./docs/security/).
Agents that scan this repository should consult `SECURITY.md` and the linked
security model before reporting issues. In particular, the core model defines
what is in and out of scope, how reports are classified, and a list of known
non-findings; each component page adds its own known non-findings.
non-findings; each component page adds its own known non-findings.
## Reference docs
| Topic | Location |
|--------------------------------|----------|
| Build, test, broker quickstart | [README.md](README.md) |
| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md), https://kafka.apache.org/contributing.html |
| Message protocol / codegen | [clients/src/main/resources/common/message/README.md](clients/src/main/resources/common/message/README.md) |
| System tests | [tests/README.md](tests/README.md) |
| JMH benchmarks | [jmh-benchmarks/README.md](jmh-benchmarks/README.md) |
| Client examples | [examples/README.md](examples/README.md) |
| Security | [SECURITY.md](SECURITY.md) |
CONTRIBUTING.md
+19
View File
@@ -4,8 +4,27 @@
It lists steps that are required before creating a PR.
### License
When you contribute code, you affirm that the contribution is your original work and that you
license the work to the project under the project's open source license. Whether or not you
state this explicitly, by submitting any copyrighted material via pull request, email, or
other means you agree to license the material under the project's open source license and
warrant that you have the legal authority to do so.
### AI-Generated Contributions
Based on the [ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html):
- If you used AI tools in preparing your PR, please commit with the `Co-Authored-By`, `Generated-by`, or similar commit trailer.
```
Co-Authored-By: <AI tool name and version>
Generated-by: <AI tool name and version>
```
Example:
```
KAFKA-9999: adding AGENTS.md
Co-Authored-By: Claude Sonnet 4.6 <claude@anthropic.com>
```
- The human author remains responsible for all changes, regardless of the tools used to create them, and must certify that you wrote or otherwise have the right to submit the code you are contributing.
build.gradle
+1
View File
@@ -285,6 +285,7 @@ if (repo != null) {
'gradle/wrapper/gradle-wrapper.properties',
'trogdor/README.md',
'**/README.md',
'**/AGENTS.md',
'**/id_rsa',
'**/id_rsa.pub',
'checkstyle/suppressions.xml',