This is an automated email from the ASF dual-hosted git repository. github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/main/pr-3337-ab047b5e2f6e2ba6b999731653a3f7722b84e6f7 in repository https://gitbox.apache.org/repos/asf/iceberg-rust.git
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
