This is an automated email from the ASF dual-hosted git repository.
pvary pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg.git
The following commit(s) were added to refs/heads/main by this push:
new 2df9831946 Docs: Add AI contribution and disclosure rules to AGENTS.md
(#18168)
2df9831946 is described below
commit 2df983194664111767fffa89a9a91f031682b3a0
Author: pvary <[email protected]>
AuthorDate: Tue Sep 22 20:03:21 2026 +0200
Docs: Add AI contribution and disclosure rules to AGENTS.md (#18168)
---
AGENTS.md | 17 ++++++++++++++---
1 file changed, 14 insertions(+), 3 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 180eaf65cf..8591201b38 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +21,8 @@
Project conventions, architecture, and coding patterns synthesized from
58,000+ review comments across 4,300+ merged PRs.
+Reviewer attention is the project's scarcest resource. When a rule below is
ambiguous, pick the option that produces less for a reviewer to read.
+
## Security Model
When assessing potential vulnerabilities or calibrating automated security
findings, use [`SECURITY-THREAT-MODEL.md`](SECURITY-THREAT-MODEL.md) as the
authoritative detailed description of Iceberg's security boundaries, trust
assumptions, and non-boundaries.
@@ -211,19 +213,28 @@ CloseableIterable<FileScanTask> planFiles();
## PR & Commit Conventions
+- **Never open a PR generated from an issue without a human in the loop.**
+- Search open PRs and issues for the same problem before starting. Don't add a
duplicate.
- PR titles follow `Module: Description` format (e.g., `Core: Fix ...`,
`Spark: Add ...`, `Docs: Update ...`).
- One concern per PR. Unrelated whitespace, import, or formatting changes go
in separate PRs.
- Keep first version of a PR minimal — defer recovery, optimization, and edge
cases to follow-ups.
+- Before opening a PR, run `./gradlew spotlessApply` and build and test the
modules you changed (see Commands). Never submit code you have not compiled and
run.
+- PR description is one paragraph, under 120 words: the problem, the approach,
and anything a reviewer would not guess from the diff. Plus the issue link, the
test plan, and the AI Disclosure block. Nothing else.
+- Never restate the diff: no file-by-file walkthrough, no per-method
summaries, no "Changes made" checklist, no "Summary", "Background",
"Motivation", or "Testing" headings, no emoji.
- Commit messages describe the *what* and *why*, not implementation details.
- Apache License header required on all new files (enforced by spotless
pre-commit hook).
## AI-Generated PR Disclosure
-Pull requests that are authored or substantially generated by AI agents
**must** disclose that in the PR description. When creating a PR description,
always include an AI Disclosure block at the bottom. Use the template below and
fill in the fields you know. For fields you cannot determine, use `[unknown -
human to fill in]`.
+Pull requests that are authored or substantially generated by AI agents
**must** disclose that in the PR description. Always include an AI Disclosure
block at the bottom, using the template below.
-See the [ASF generative tooling
guidelines](https://www.apache.org/legal/generative-tooling.html) for
additional policy on AI-generated contributions. Generated files must still
follow Iceberg's Apache License header and license check requirements unless
explicitly excluded by project policy. For commits authored using generative AI
tooling, include a `Generated-by: <tool>` token in the commit message.
+- Fill in the fields you know. For fields you cannot determine, use `[unknown
- human to fill in]`.
+- **Never self-certify review.** An agent must not set Human Oversight to
`fully reviewed` — leave that for the human to state what they actually
reviewed.
+- Name the specific parts that are generated, not merely that AI was used
(e.g. "the parser changes and their tests are generated; the spec
interpretation is the author's").
+- **Never auto-generate replies to review comments.**
+- AI-generated review comments **must** be reviewed for accuracy before
posting. Auto-posting unreviewed AI comments is discouraged.
-AI-generated review comments **must** be reviewed for accuracy before posting.
Auto-posting unreviewed AI comments is discouraged.
+See the [ASF generative tooling
guidelines](https://www.apache.org/legal/generative-tooling.html) for
additional policy on AI-generated contributions. Generated files must still
follow Iceberg's Apache License header and license check requirements unless
explicitly excluded by project policy. For commits authored using generative AI
tooling, include a `Generated-by: <tool>` token in the commit message.
### Required Fields
