This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-rust.git
The following commit(s) were added to refs/heads/main by this push:
new 776648bee docs: add agent guidance to reduce verbosity (#3337)
776648bee is described below
commit 776648bee4c52ece8a057cfcf0d7756416299ba8
Author: Kevin Liu <[email protected]>
AuthorDate: Thu Oct 8 11:09:32 2026 +0000
docs: add agent guidance to reduce verbosity (#3337)
* docs: add agent guidance on code comments and API surface
Co-authored-by: Copilot App <[email protected]>
* docs: add agent guidance on PR descriptions
Co-authored-by: Copilot App <[email protected]>
* docs: separate always-flag review rules
Co-authored-by: Copilot App <[email protected]>
* docs: soften always-flag wording
Co-authored-by: Copilot App <[email protected]>
* docs: drop refactor test from comment guidance
Co-authored-by: Copilot App <[email protected]>
* docs: base pub guidance on intended API
Co-authored-by: Copilot App <[email protected]>
* docs: clarify visibility guidance
Co-authored-by: Copilot App <[email protected]>
* docs: add reuse and test duplication guidance
Co-authored-by: Copilot App <[email protected]>
* docs: trim reuse guidance
Co-authored-by: Copilot App <[email protected]>
* Apply batched suggestions from code review
Co-authored-by: Matt Butrovich <[email protected]>
---------
Co-authored-by: Copilot App <[email protected]>
Co-authored-by: blackmwk <[email protected]>
Co-authored-by: Matt Butrovich <[email protected]>
---
.github/copilot-instructions.md | 12 ++++++++++++
AGENTS.md | 38 ++++++++++++++++++++++++++++++++++++++
2 files changed, 50 insertions(+)
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 3744d6f43..c00ef406b 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -19,3 +19,15 @@ When reviewing pull requests, follow these rules to avoid
noise and redundancy:
- First-time contributors: For users new to this repository,
explicitly instruct them to "Please check and address all review
comments in this PR."
+
+Also flag these, once per PR with the locations:
+
+- Comment churn: Code comments or docs that restate the code, narrate
+ history, or justify review decisions.
+- Unrelated edits: Renames, reformatting, or reordering of code the
+ change does not otherwise need.
+- Duplication: New helpers, types, or tests that duplicate existing ones.
+- API growth: New public API the change does not need. Check new entries
+ in `public-api.txt`.
+- PR description: Descriptions that restate the diff or pad the
+ template. Mention it in the review summary.
diff --git a/AGENTS.md b/AGENTS.md
index 22ddb2bbd..5a1106e0b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,6 +22,44 @@
This file provides repository-specific guidance for automated agents working
in this repository.
+## Comments, docs, and diff scope
+
+Default to no comment. Leave existing comments as they are unless you change
+the code they describe or they are wrong.
+
+- Comment only what the code cannot say: invariants, non-obvious
+ constraints, links to external behavior. Do not restate the code.
+- Do not describe how the code changed or explain review history
+ ("previously", "instead of", "unlike X"). Put that in the commit message
+ or PR description.
+- Public items get a one-line doc summary of what they do for the caller,
+ not how. Expand only for contract the caller must know, such as the
+ errors it returns (`# Errors`) or when it panics (`# Panics`).
+- Test names say what they check. Do not narrate asserts.
+- Cover the edge cases and error paths the change adds, not only the
+ happy path.
+- Build the expected value and assert equality with it, rather than
+ checking fields one at a time.
+- Do not add tests that duplicate existing coverage.
+- Do not rename, reformat, refactor, or reorder code unrelated to the
+ change. A bug fix does not carry an API redesign.
+- Reuse existing helpers, types, and test fixtures (such as
+ `TableTestFixture`) before adding new ones. Use arrow-rs kernels
+ instead of reimplementing them.
+- Use the narrowest visibility that works. Make items `pub` only when they
+ are part of the API the change intends to expose. Run
+ `make generate-public-api` to update each crate's `public-api.txt`, and
+ check its diff for API growth.
+
+## Pull requests
+
+- Follow the PR template. Keep each section short: the problem, the
+ approach, and anything a reviewer would not guess from the diff. In
+ AI Disclosure, name the areas of uncertainty or assumptions a reviewer
+ should focus on.
+- Do not restate the diff: no file-by-file walkthroughs, per-function
+ summaries, or "changes made" checklists.
+
## Security Model
When assessing potential vulnerabilities or calibrating automated security
