{"owner":"apache","repo":"pulsar","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Agent guide for Apache Pulsar\n\nSupplemental guidance for AI coding assistants (Claude Code, Copilot, Cursor, Gemini, Codex, Aider,\nand similar tools) working in this repository. Keep this file short — it is a **router**. The detail\nlives in the human-facing docs linked below; read the one that fits your task rather than pulling\neverything into context up front.\n\nApache Pulsar is a distributed pub-sub messaging and streaming platform. The codebase is\nperformance-critical, heavily asynchronous, and concurrency-sensitive. Prioritize **correctness,\nthread safety, performance, maintainability, and backward compatibility**.\n\n## Licensing and provenance (read first)\n\nApache Pulsar is licensed under the Apache License 2.0, and all contributions must meet the ASF's\n[Generative Tooling guidance](https://www.apache.org/legal/generative-tooling.html):\n\n- **A human is in the loop and is accountable.** Every pull request and every security report must be\n submitted by a human contributor who has reviewed and verified the change and takes responsibility\n for it. Fully autonomous agents (e.g. OpenClaw-style bots) opening PRs or filing reports on their own\n are not acceptable — the AI assists, the human is accountable.\n- **Don't introduce code of incompatible or unknown provenance.** Never copy verbatim from\n GPL/AGPL/LGPL, proprietary, or unlicensed sources (including Stack Overflow / blog / forum snippets of\n unclear licensing), and don't use a tool whose terms restrict the output inconsistently with open\n source. Reimplement from specifications or Apache-compatible sources, and follow the\n [ASF 3rd Party Licensing Policy](https://www.apache.org/legal/resolved.html).\n- **Every new source file needs the ASF license header** (Spotless enforces this — copy the form from\n an existing `.java` file).\n- **Consider attributing AI assistance.** When AI tooling assisted on a change, consider adding an\n `Assisted-by: ` commit trailer (the default, since a human still does the final\n review); `Generated-by: ` is for minimally-modified generated output.\n\n## Canonical docs (read the one that fits the task)\n\n| Doc | Use for |\n|-----|---------|\n| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Local dev workflow: building (prerequisites, build/lint commands), running tests & test groups, integration tests, Personal CI, PR conventions, security reporting. |\n| [`ARCHITECTURE.md`](ARCHITECTURE.md) | Big-picture module map, the Gradle build infrastructure and how to change build files (convention plugins, version catalog, the module-name-vs-directory gotcha), the concurrency model and backpressure, and the `pip/` proposals. |\n| [`CODING.md`](CODING.md) | Coding conventions: style, async/`CompletableFuture`, concurrency, logging ([slog](https://github.com/merlimat/slog)), dependencies, backward compatibility, testing, and the review checklist. |\n| [`SECURITY.md`](SECURITY.md) | Reporting a vulnerability, disclosure hygiene, and checking exposure to an already-public CVE. |\n\nThe authoritative project documentation is at , whose source lives in the\n[`apache/pulsar-site`](https://github.com/apache/pulsar-site) repository (where documentation changes\nare contributed). The files above and the website remain the source of truth — this guide just layers\nAI-specific pointers on top.\n\n## Agent guardrails\n\nA few rules matter specifically when an AI tool makes the change, on top of the canonical docs above:\n\n- **Verify, don't fabricate.** Before you use a class, method, field, configuration key, Gradle task,\n plugin, or DSL name, confirm it actually exists (search the code or the build files) — don't invent\n APIs, test assertions, or symbol names. Don't assert a CVE is \"fixed\" / \"not affected\" without\n checking the merged PRs and the shipped version.\n- **Confirm state-changing actions.** Get the user's explicit confirmation before pushing, opening or\n updating a PR, or posting a comment. Being asked to start a task is not standing authorization for\n these outward-facing actions — see *Licensing and provenance* above.\n- **A clean local run is weak evidence for concurrency/data race fixes** (timing- and\n platform-dependent). See [`CODING.md`](CODING.md#reproducing-concurrency--memory-visibility-bugs).\n- **Follow Java style guidance.** For Java conventions, including imports over fully qualified class\n names, follow [`CODING.md`](CODING.md#style).\n- **Check before claiming conformance.** Run `./gradlew quickCheck` for a fast source-only pass\n (license headers + checkstyle, no compilation) or `./gradlew sanityCheck` to also\n compile every module's main and test sources; neither builds shadow jars. See\n [`CONTRIBUTING.md`](CONTRIBUTING.md#building).\n\n## Critical rules\n\n1. **Don't break backward compatibility** — public APIs, client compatibility, wire protocol, and\n serialized/metadata formats. Servers must interoperate with older and newer clients.\n2. **Never block on async/event-loop threads;** methods returning `CompletableFuture` must not throw\n synchronously. See [`CODING.md`](CODING.md#asynchronous-programming).\n3. **Logging:** prefer [slog](https://github.com/merlimat/slog) via `@CustomLog`; default new logs to\n `TRACE`/`DEBUG`, not `INFO`.\n4. **Tests:** scope runs with `--tests`; no reflection into private state (use a `@VisibleForTesting`\n package-private accessor); release buffers and resources.\n5. **PRs:** semantic `[type][scope]` title; describe **motivation** and **modifications**; do not\n rebase once the PR is open in `apache/pulsar` — merge upstream `master` instead.\n6. **Security:** never disclose a vulnerability — or the security nature of a change — in a public\n issue, PR, or commit. See [`SECURITY.md`](SECURITY.md).\n7. **Stay in scope.** Keep a change focused on its task; don't bundle unrelated drive-by refactors or\n generate broad mass-refactoring PRs. Discuss large refactorings on `dev@pulsar.apache.org` first.\n See [`CONTRIBUTING.md`](CONTRIBUTING.md#pull-requests).\n\n## Where to ask\n\n- Dev mailing list: · Slack: \n- Issues: · Discussions: \n"},"files":{"AGENTS.md":"# Agent guide for Apache Pulsar\n\nSupplemental guidance for AI coding assistants (Claude Code, Copilot, Cursor, Gemini, Codex, Aider,\nand similar tools) working in this repository. Keep this file short — it is a **router**. The detail\nlives in the human-facing docs linked below; read the one that fits your task rather than pulling\neverything into context up front.\n\nApache Pulsar is a distributed pub-sub messaging and streaming platform. The codebase is\nperformance-critical, heavily asynchronous, and concurrency-sensitive. Prioritize **correctness,\nthread safety, performance, maintainability, and backward compatibility**.\n\n## Licensing and provenance (read first)\n\nApache Pulsar is licensed under the Apache License 2.0, and all contributions must meet the ASF's\n[Generative Tooling guidance](https://www.apache.org/legal/generative-tooling.html):\n\n- **A human is in the loop and is accountable.** Every pull request and every security report must be\n submitted by a human contributor who has reviewed and verified the change and takes responsibility\n for it. Fully autonomous agents (e.g. OpenClaw-style bots) opening PRs or filing reports on their own\n are not acceptable — the AI assists, the human is accountable.\n- **Don't introduce code of incompatible or unknown provenance.** Never copy verbatim from\n GPL/AGPL/LGPL, proprietary, or unlicensed sources (including Stack Overflow / blog / forum snippets of\n unclear licensing), and don't use a tool whose terms restrict the output inconsistently with open\n source. Reimplement from specifications or Apache-compatible sources, and follow the\n [ASF 3rd Party Licensing Policy](https://www.apache.org/legal/resolved.html).\n- **Every new source file needs the ASF license header** (Spotless enforces this — copy the form from\n an existing `.java` file).\n- **Consider attributing AI assistance.** When AI tooling assisted on a change, consider adding an\n `Assisted-by: ` commit trailer (the default, since a human still does the final\n review); `Generated-by: ` is for minimally-modified generated output.\n\n## Canonical docs (read the one that fits the task)\n\n| Doc | Use for |\n|-----|---------|\n| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Local dev workflow: building (prerequisites, build/lint commands), running tests & test groups, integration tests, Personal CI, PR conventions, security reporting. |\n| [`ARCHITECTURE.md`](ARCHITECTURE.md) | Big-picture module map, the Gradle build infrastructure and how to change build files (convention plugins, version catalog, the module-name-vs-directory gotcha), the concurrency model and backpressure, and the `pip/` proposals. |\n| [`CODING.md`](CODING.md) | Coding conventions: style, async/`CompletableFuture`, concurrency, logging ([slog](https://github.com/merlimat/slog)), dependencies, backward compatibility, testing, and the review checklist. |\n| [`SECURITY.md`](SECURITY.md) | Reporting a vulnerability, disclosure hygiene, and checking exposure to an already-public CVE. |\n\nThe authoritative project documentation is at , whose source lives in the\n[`apache/pulsar-site`](https://github.com/apache/pulsar-site) repository (where documentation changes\nare contributed). The files above and the website remain the source of truth — this guide just layers\nAI-specific pointers on top.\n\n## Agent guardrails\n\nA few rules matter specifically when an AI tool makes the change, on top of the canonical docs above:\n\n- **Verify, don't fabricate.** Before you use a class, method, field, configuration key, Gradle task,\n plugin, or DSL name, confirm it actually exists (search the code or the build files) — don't invent\n APIs, test assertions, or symbol names. Don't assert a CVE is \"fixed\" / \"not affected\" without\n checking the merged PRs and the shipped version.\n- **Confirm state-changing actions.** Get the user's explicit confirmation before pushing, opening or\n updating a PR, or posting a comment. Being asked to start a task is not standing authorization for\n these outward-facing actions — see *Licensing and provenance* above.\n- **A clean local run is weak evidence for concurrency/data race fixes** (timing- and\n platform-dependent). See [`CODING.md`](CODING.md#reproducing-concurrency--memory-visibility-bugs).\n- **Follow Java style guidance.** For Java conventions, including imports over fully qualified class\n names, follow [`CODING.md`](CODING.md#style).\n- **Check before claiming conformance.** Run `./gradlew quickCheck` for a fast source-only pass\n (license headers + checkstyle, no compilation) or `./gradlew sanityCheck` to also\n compile every module's main and test sources; neither builds shadow jars. See\n [`CONTRIBUTING.md`](CONTRIBUTING.md#building).\n\n## Critical rules\n\n1. **Don't break backward compatibility** — public APIs, client compatibility, wire protocol, and\n serialized/metadata formats. Servers must interoperate with older and newer clients.\n2. **Never block on async/event-loop threads;** methods returning `CompletableFuture` must not throw\n synchronously. See [`CODING.md`](CODING.md#asynchronous-programming).\n3. **Logging:** prefer [slog](https://github.com/merlimat/slog) via `@CustomLog`; default new logs to\n `TRACE`/`DEBUG`, not `INFO`.\n4. **Tests:** scope runs with `--tests`; no reflection into private state (use a `@VisibleForTesting`\n package-private accessor); release buffers and resources.\n5. **PRs:** semantic `[type][scope]` title; describe **motivation** and **modifications**; do not\n rebase once the PR is open in `apache/pulsar` — merge upstream `master` instead.\n6. **Security:** never disclose a vulnerability — or the security nature of a change — in a public\n issue, PR, or commit. See [`SECURITY.md`](SECURITY.md).\n7. **Stay in scope.** Keep a change focused on its task; don't bundle unrelated drive-by refactors or\n generate broad mass-refactoring PRs. Discuss large refactorings on `dev@pulsar.apache.org` first.\n See [`CONTRIBUTING.md`](CONTRIBUTING.md#pull-requests).\n\n## Where to ask\n\n- Dev mailing list: · Slack: \n- Issues: · Discussions: \n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Agent guide for Apache Pulsar\n\nSupplemental guidance for AI coding assistants (Claude Code, Copilot, Cursor, Gemini, Codex, Aider,\nand similar tools) working in this repository. Keep this file short — it is a **router**. The detail\nlives in the human-facing docs linked below; read the one that fits your task rather than pulling\neverything into context up front.\n\nApache Pulsar is a distributed pub-sub messaging and streaming platform. The codebase is\nperformance-critical, heavily asynchronous, and concurrency-sensitive. Prioritize **correctness,\nthread safety, performance, maintainability, and backward compatibility**.\n\n## Licensing and provenance (read first)\n\nApache Pulsar is licensed under the Apache License 2.0, and all contributions must meet the ASF's\n[Generative Tooling guidance](https://www.apache.org/legal/generative-tooling.html):\n\n- **A human is in the loop and is accountable.** Every pull request and every security report must be\n submitted by a human contributor who has reviewed and verified the change and takes responsibility\n for it. Fully autonomous agents (e.g. OpenClaw-style bots) opening PRs or filing reports on their own\n are not acceptable — the AI assists, the human is accountable.\n- **Don't introduce code of incompatible or unknown provenance.** Never copy verbatim from\n GPL/AGPL/LGPL, proprietary, or unlicensed sources (including Stack Overflow / blog / forum snippets of\n unclear licensing), and don't use a tool whose terms restrict the output inconsistently with open\n source. Reimplement from specifications or Apache-compatible sources, and follow the\n [ASF 3rd Party Licensing Policy](https://www.apache.org/legal/resolved.html).\n- **Every new source file needs the ASF license header** (Spotless enforces this — copy the form from\n an existing `.java` file).\n- **Consider attributing AI assistance.** When AI tooling assisted on a change, consider adding an\n `Assisted-by: ` commit trailer (the default, since a human still does the final\n review); `Generated-by: ` is for minimally-modified generated output.\n\n## Canonical docs (read the one that fits the task)\n\n| Doc | Use for |\n|-----|---------|\n| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Local dev workflow: building (prerequisites, build/lint commands), running tests & test groups, integration tests, Personal CI, PR conventions, security reporting. |\n| [`ARCHITECTURE.md`](ARCHITECTURE.md) | Big-picture module map, the Gradle build infrastructure and how to change build files (convention plugins, version catalog, the module-name-vs-directory gotcha), the concurrency model and backpressure, and the `pip/` proposals. |\n| [`CODING.md`](CODING.md) | Coding conventions: style, async/`CompletableFuture`, concurrency, logging ([slog](https://github.com/merlimat/slog)), dependencies, backward compatibility, testing, and the review checklist. |\n| [`SECURITY.md`](SECURITY.md) | Reporting a vulnerability, disclosure hygiene, and checking exposure to an already-public CVE. |\n\nThe authoritative project documentation is at , whose source lives in the\n[`apache/pulsar-site`](https://github.com/apache/pulsar-site) repository (where documentation changes\nare contributed). The files above and the website remain the source of truth — this guide just layers\nAI-specific pointers on top.\n\n## Agent guardrails\n\nA few rules matter specifically when an AI tool makes the change, on top of the canonical docs above:\n\n- **Verify, don't fabricate.** Before you use a class, method, field, configuration key, Gradle task,\n plugin, or DSL name, confirm it actually exists (search the code or the build files) — don't invent\n APIs, test assertions, or symbol names. Don't assert a CVE is \"fixed\" / \"not affected\" without\n checking the merged PRs and the shipped version.\n- **Confirm state-changing actions.** Get the user's explicit confirmation before pushing, opening or\n updating a PR, or posting a comment. Being asked to start a task is not standing authorization for\n these outward-facing actions — see *Licensing and provenance* above.\n- **A clean local run is weak evidence for concurrency/data race fixes** (timing- and\n platform-dependent). See [`CODING.md`](CODING.md#reproducing-concurrency--memory-visibility-bugs).\n- **Follow Java style guidance.** For Java conventions, including imports over fully qualified class\n names, follow [`CODING.md`](CODING.md#style).\n- **Check before claiming conformance.** Run `./gradlew quickCheck` for a fast source-only pass\n (license headers + checkstyle, no compilation) or `./gradlew sanityCheck` to also\n compile every module's main and test sources; neither builds shadow jars. See\n [`CONTRIBUTING.md`](CONTRIBUTING.md#building).\n\n## Critical rules\n\n1. **Don't break backward compatibility** — public APIs, client compatibility, wire protocol, and\n serialized/metadata formats. Servers must interoperate with older and newer clients.\n2. **Never block on async/event-loop threads;** methods returning `CompletableFuture` must not throw\n synchronously. See [`CODING.md`](CODING.md#asynchronous-programming).\n3. **Logging:** prefer [slog](https://github.com/merlimat/slog) via `@CustomLog`; default new logs to\n `TRACE`/`DEBUG`, not `INFO`.\n4. **Tests:** scope runs with `--tests`; no reflection into private state (use a `@VisibleForTesting`\n package-private accessor); release buffers and resources.\n5. **PRs:** semantic `[type][scope]` title; describe **motivation** and **modifications**; do not\n rebase once the PR is open in `apache/pulsar` — merge upstream `master` instead.\n6. **Security:** never disclose a vulnerability — or the security nature of a change — in a public\n issue, PR, or commit. See [`SECURITY.md`](SECURITY.md).\n7. **Stay in scope.** Keep a change focused on its task; don't bundle unrelated drive-by refactors or\n generate broad mass-refactoring PRs. Discuss large refactorings on `dev@pulsar.apache.org` first.\n See [`CONTRIBUTING.md`](CONTRIBUTING.md#pull-requests).\n\n## Where to ask\n\n- Dev mailing list: · Slack: \n- Issues: · Discussions: \n","category":"root","tokens":1564}]}