From 15fc56b02617ba24d6bcf802aea6c2584593117c Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Sun, 5 Jul 2026 15:08:53 +0100 Subject: [PATCH 1/9] Add generic AGENTS.md file --- AGENTS.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000000..1a80942bbb10 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,128 @@ + + +# AGENTS.md + +This file provides guidance for AI coding agents working on Apache Arrow. + +Apache Arrow is a multi-language toolbox for accelerated data interchange +and in-memory processing. + +## Repository Layout + +| Directory | Description | +|-----------|-------------| +| `cpp/` | Core C++ library (libarrow, Parquet, Flight, Gandiva, etc.) | +| `python/` | PyArrow (Python bindings for libarrow) | +| `r/` | R package | +| `c_glib/` | C/GLib bindings | +| `ruby/` | Ruby bindings | +| `matlab/` | MATLAB implementation | +| `docs/` | Sphinx documentation source | +| `ci/` | CI configuration (Docker, scripts) | +| `dev/` | Developer tools and release scripts | +| `format/` | Arrow columnar format specification | +| `testing/` | Shared test data (integration testing) | + +Several implementations have moved to their own repositories: + +- **Java**: [apache/arrow-java](https://github.com/apache/arrow-java) +- **Go**: [apache/arrow-go](https://github.com/apache/arrow-go) +- **Rust**: [apache/arrow-rs](https://github.com/apache/arrow-rs) +- **C#**: [apache/arrow-csharp](https://github.com/apache/arrow-csharp) +- **JavaScript**: [apache/arrow-js](https://github.com/apache/arrow-js) +- **Swift**: [apache/arrow-swift](https://github.com/apache/arrow-swift) +- **Julia**: [apache/arrow-julia](https://github.com/apache/arrow-julia) + +## Issue Conventions + +- Prefix the issue title with the component name in brackets: + `[C++][Python] Short description of the problem` +- Do NOT include a `GH-` prefix in issue titles (that is only for PRs). +- Search existing issues before creating a new one. + +## Pull Request Conventions + +### Title Format + +``` +GH-: [Component] Short description +``` + +Example: `GH-14736: [C++][Python] Ensure no validity bitmap in UnionArray::SetData` + +### MINOR Changes + +For trivial documentation or typo fixes affecting no more than 2 files and +no more than 500 words, you may skip creating an issue and prefix the PR +title with `MINOR:` instead: + +``` +MINOR: [Docs] Fix typo in memory.rst +``` + +Do NOT combine `MINOR:` with a `GH-` number. + +### PR Description + +Fill in all four sections of the PR template: + +1. **Rationale for this change** - Why is this needed? +2. **What changes are included in this PR?** - What did you do? +3. **Are these changes tested?** - How are they validated? +4. **Are there any user-facing changes?** - Yes/No with brief explanation + +Descriptions should be concise and to the point — do not restate things +that are obvious from reading the diff. + +Only keep the "Critical Fix" or "Breaking changes" flags in the description +if they genuinely apply. Remove them otherwise. + +## Pre-commit Hooks + +```bash +pip install pre-commit +pre-commit install +pre-commit run -a # all hooks +pre-commit run --all-files # single component (alias from .pre-commit-config.yaml) +``` + +Always run the relevant pre-commit checks before submitting a PR. + +## Testing + +Run relevant tests locally before submitting a PR. See the +[Testing](https://arrow.apache.org/docs/developers/guide/step_by_step/testing.html) +section of the contributor guide for component-specific instructions. + +## AI-Generated Code Policy + +See: https://arrow.apache.org/docs/dev/developers/overview.html#ai-generated-code + +## Component-Specific Guides + +Some subdirectories may contain their own `AGENTS.md` with language-specific +build instructions, testing commands, and coding conventions. Check the +relevant component directory before starting work. + +## Further Resources + +- [New Contributor's Guide](https://arrow.apache.org/docs/developers/guide/index.html) +- [Contributing Overview](https://arrow.apache.org/docs/developers/overview.html) +- [CONTRIBUTING.md](CONTRIBUTING.md) From 339307a0049473bf23724d1be871756d3dcf880e Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Mon, 6 Jul 2026 16:50:03 +0100 Subject: [PATCH 2/9] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 1a80942bbb10..45b1d598552e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,7 +100,7 @@ if they genuinely apply. Remove them otherwise. pip install pre-commit pre-commit install pre-commit run -a # all hooks -pre-commit run --all-files # single component (alias from .pre-commit-config.yaml) +pre-commit run --all-files # e.g. python, cpp (see aliases in .pre-commit-config.yaml) ``` Always run the relevant pre-commit checks before submitting a PR. From f5e1013854a8617a8072bbcf701f4a8503cf2367 Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Thu, 9 Jul 2026 12:43:34 +0100 Subject: [PATCH 3/9] Update AGENTS file with feedback in mind --- AGENTS.md | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 45b1d598552e..20d1a7f052e3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,10 +50,28 @@ Several implementations have moved to their own repositories: - **Swift**: [apache/arrow-swift](https://github.com/apache/arrow-swift) - **Julia**: [apache/arrow-julia](https://github.com/apache/arrow-julia) +## Git Conventions + +### Remote Names + +- `upstream` → `apache/arrow` (fetch from here) +- `origin` → your fork (push PR branches here) + +Verify with `git remote -v` before pushing. Never push directly to +`upstream`. + +### Commit Messages + +Use imperative mood and focus on *why*, not *what*. + +Good: `Fix UnionArray validation when type codes are non-contiguous` +Bad: `Fixed the bug in union array` + ## Issue Conventions -- Prefix the issue title with the component name in brackets: - `[C++][Python] Short description of the problem` +- Follow the issue templates at + https://github.com/apache/arrow/tree/main/.github/ISSUE_TEMPLATE + when creating a new issue. - Do NOT include a `GH-` prefix in issue titles (that is only for PRs). - Search existing issues before creating a new one. @@ -81,18 +99,17 @@ Do NOT combine `MINOR:` with a `GH-` number. ### PR Description -Fill in all four sections of the PR template: - -1. **Rationale for this change** - Why is this needed? -2. **What changes are included in this PR?** - What did you do? -3. **Are these changes tested?** - How are they validated? -4. **Are there any user-facing changes?** - Yes/No with brief explanation +Fill in all four sections of the PR template at +https://github.com/apache/arrow/blob/main/.github/pull_request_template.md Descriptions should be concise and to the point — do not restate things that are obvious from reading the diff. -Only keep the "Critical Fix" or "Breaking changes" flags in the description -if they genuinely apply. Remove them otherwise. +### AI-Generated Content + +Never open pull requests or post comments to GitHub automatically. +A human must review all changes locally and write the PR description +before submitting. ## Pre-commit Hooks From 477d7d3a1e62a086cd640f08a4113262e245e031 Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Thu, 9 Jul 2026 12:46:22 +0100 Subject: [PATCH 4/9] Enhance phrasing --- AGENTS.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 20d1a7f052e3..7785ad363573 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,6 +50,18 @@ Several implementations have moved to their own repositories: - **Swift**: [apache/arrow-swift](https://github.com/apache/arrow-swift) - **Julia**: [apache/arrow-julia](https://github.com/apache/arrow-julia) +## License Headers + +All new source files must include the Apache License 2.0 header. +Copy the header format from an existing file in the same directory. + +## Cross-Language Dependencies + +The C++ library (`cpp/`) is the shared core. PyArrow, R, and MATLAB +bind directly to it. C/GLib wraps the C++ library, and Ruby binds to +C/GLib. Changes in `cpp/` can break any of these downstream components. +When modifying C++ code, consider the impact on dependent bindings. + ## Git Conventions ### Remote Names From 6892982f22744979f9f0425131eeaf19c1f23866 Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Thu, 9 Jul 2026 12:50:48 +0100 Subject: [PATCH 5/9] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7785ad363573..12eff43d2b7d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -101,13 +101,11 @@ Example: `GH-14736: [C++][Python] Ensure no validity bitmap in UnionArray::SetDa For trivial documentation or typo fixes affecting no more than 2 files and no more than 500 words, you may skip creating an issue and prefix the PR -title with `MINOR:` instead: +title with `MINOR: ` instead: -``` -MINOR: [Docs] Fix typo in memory.rst -``` + MINOR: [Docs] Fix typo in memory.rst -Do NOT combine `MINOR:` with a `GH-` number. +Do NOT combine `MINOR: ` with a `GH-` number. ### PR Description From 384e546612d1819c5c554bf609b0315d22d275ae Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Tue, 27 Oct 2026 17:58:38 +0000 Subject: [PATCH 6/9] Make changes based on best practices and looking at other projects' AGENTS files --- AGENTS.md | 199 +++++++++++++++++++++++++----------------------------- 1 file changed, 91 insertions(+), 108 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 12eff43d2b7d..e8b8427ad9f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,77 +19,73 @@ # AGENTS.md -This file provides guidance for AI coding agents working on Apache Arrow. +Guidance for AI coding agents working on Apache Arrow. It covers the +conventions shared across the repository; component directories may +carry their own `AGENTS.md` with build and test commands, and the +closest file to the code you are editing takes precedence. + +## Repository Gotchas + +- This is a monorepo. The C++ library (`cpp/`) is the shared core; + PyArrow (`python/`), R (`r/`), and MATLAB (`matlab/`) bind to it + directly, C/GLib (`c_glib/`) wraps it, and Ruby (`ruby/`) binds to + C/GLib. A change in `cpp/` can break any of these, so check the + dependent bindings when you touch C++. +- Java, Go, Rust, C#, JavaScript, Swift, and Julia are **not** in this + repository. They live in `apache/arrow-java`, `apache/arrow-go`, + `apache/arrow-rs`, `apache/arrow-csharp`, `apache/arrow-js`, + `apache/arrow-swift`, and `apache/arrow-julia`. Do not look for or + recreate them here. +- Generated files are committed and must not be hand-edited: + `r/R/arrowExports.R` and `r/src/arrowExports.cpp` (regenerated by + `r/data-raw/codegen.R`), and everything under `cpp/src/generated/`. +- Every new source file needs the Apache License 2.0 header. Copy it + from an existing file in the same directory. CI's license check + (`rat`) rejects files without one. + +## Building and Testing + +Each component has its own toolchain. Read the developer docs for the +component before building, rather than guessing: + +- C++: `docs/source/developers/cpp/building.rst` +- Python: `docs/source/developers/python/building.rst` +- R: `r/vignettes/developers/setup.Rmd` +- Everything else: `docs/source/developers/` +- Running tests, per component: + `docs/source/developers/guide/step_by_step/testing.rst` + +Run the relevant tests locally before opening a PR, and run pre-commit +on the files you changed: -Apache Arrow is a multi-language toolbox for accelerated data interchange -and in-memory processing. - -## Repository Layout - -| Directory | Description | -|-----------|-------------| -| `cpp/` | Core C++ library (libarrow, Parquet, Flight, Gandiva, etc.) | -| `python/` | PyArrow (Python bindings for libarrow) | -| `r/` | R package | -| `c_glib/` | C/GLib bindings | -| `ruby/` | Ruby bindings | -| `matlab/` | MATLAB implementation | -| `docs/` | Sphinx documentation source | -| `ci/` | CI configuration (Docker, scripts) | -| `dev/` | Developer tools and release scripts | -| `format/` | Arrow columnar format specification | -| `testing/` | Shared test data (integration testing) | - -Several implementations have moved to their own repositories: - -- **Java**: [apache/arrow-java](https://github.com/apache/arrow-java) -- **Go**: [apache/arrow-go](https://github.com/apache/arrow-go) -- **Rust**: [apache/arrow-rs](https://github.com/apache/arrow-rs) -- **C#**: [apache/arrow-csharp](https://github.com/apache/arrow-csharp) -- **JavaScript**: [apache/arrow-js](https://github.com/apache/arrow-js) -- **Swift**: [apache/arrow-swift](https://github.com/apache/arrow-swift) -- **Julia**: [apache/arrow-julia](https://github.com/apache/arrow-julia) - -## License Headers - -All new source files must include the Apache License 2.0 header. -Copy the header format from an existing file in the same directory. - -## Cross-Language Dependencies - -The C++ library (`cpp/`) is the shared core. PyArrow, R, and MATLAB -bind directly to it. C/GLib wraps the C++ library, and Ruby binds to -C/GLib. Changes in `cpp/` can break any of these downstream components. -When modifying C++ code, consider the impact on dependent bindings. - -## Git Conventions - -### Remote Names - -- `upstream` → `apache/arrow` (fetch from here) -- `origin` → your fork (push PR branches here) - -Verify with `git remote -v` before pushing. Never push directly to -`upstream`. - -### Commit Messages +```bash +pip install pre-commit +pre-commit install +pre-commit run --files +pre-commit run --all-files r # one component; aliases are listed in .pre-commit-config.yaml +pre-commit run -a # every hook +``` -Use imperative mood and focus on *why*, not *what*. +## Git -Good: `Fix UnionArray validation when type codes are non-contiguous` -Bad: `Fixed the bug in union array` +- `upstream` is `apache/arrow`; `origin` is the contributor's fork. + Fetch from `upstream`, push branches to `origin`, and check + `git remote -v` before pushing. Never push to `upstream`. +- PRs are squash-merged, so the PR title and description become the + commit message. Spend effort there rather than on individual commits. -## Issue Conventions +## Issues -- Follow the issue templates at - https://github.com/apache/arrow/tree/main/.github/ISSUE_TEMPLATE - when creating a new issue. -- Do NOT include a `GH-` prefix in issue titles (that is only for PRs). -- Search existing issues before creating a new one. +- Prefix the title with the component(s) in brackets: + `[C++][Python] Short description of the problem`. +- Do NOT include a `GH-` prefix in issue titles. That is for PR titles + only, where it refers to the issue being fixed. +- Search existing issues before creating one, and use the templates in + `.github/ISSUE_TEMPLATE/`. -## Pull Request Conventions +## Pull Requests -### Title Format +Title format, checked by CI: ``` GH-: [Component] Short description @@ -97,59 +93,46 @@ GH-: [Component] Short description Example: `GH-14736: [C++][Python] Ensure no validity bitmap in UnionArray::SetData` -### MINOR Changes +A PR may use `MINOR: [Component] Short description` instead, with no +issue, only if it is a grammar, usage, or spelling fix touching at +most 2 files, or a documentation update touching at most 2 files and +under 500 words. Note the space after `MINOR:`. Never combine `MINOR: ` +with a `GH-` number. -For trivial documentation or typo fixes affecting no more than 2 files and -no more than 500 words, you may skip creating an issue and prefix the PR -title with `MINOR: ` instead: +Fill in every section of `.github/pull_request_template.md`: - MINOR: [Docs] Fix typo in memory.rst +- Keep each section to a sentence or two. Do not restate what the diff + already shows. +- Delete the "breaking changes" and "Critical Fix" lines unless they + genuinely apply. +- Complete the "Was AI used for this PR?" checkboxes truthfully, + including who reviewed the change before submission. -Do NOT combine `MINOR: ` with a `GH-` number. +## Working with AI Tools -### PR Description +Arrow's policy on AI-generated contributions is in +`docs/source/developers/overview.rst` under "AI-generated code". +In practice: -Fill in all four sections of the PR template at -https://github.com/apache/arrow/blob/main/.github/pull_request_template.md +- A human reviews every change locally, understands it, and is + accountable for the PR. Do not open a PR or post to GitHub without + that review. +- Anything an agent drafts that is posted to GitHub (PR descriptions, + comments, reviews) must say so, in the template's disclosure section + or in a short attribution line at the end of the message. +- Never tag or ping maintainers. +- Keep PRs small and focused. Avoid verbose comments, unnecessary test + cases, and changes outside the scope of the issue. -Descriptions should be concise and to the point — do not restate things -that are obvious from reading the diff. +## Boundaries -### AI-Generated Content - -Never open pull requests or post comments to GitHub automatically. -A human must review all changes locally and write the PR description -before submitting. - -## Pre-commit Hooks - -```bash -pip install pre-commit -pre-commit install -pre-commit run -a # all hooks -pre-commit run --all-files # e.g. python, cpp (see aliases in .pre-commit-config.yaml) -``` - -Always run the relevant pre-commit checks before submitting a PR. - -## Testing - -Run relevant tests locally before submitting a PR. See the -[Testing](https://arrow.apache.org/docs/developers/guide/step_by_step/testing.html) -section of the contributor guide for component-specific instructions. - -## AI-Generated Code Policy - -See: https://arrow.apache.org/docs/dev/developers/overview.html#ai-generated-code - -## Component-Specific Guides - -Some subdirectories may contain their own `AGENTS.md` with language-specific -build instructions, testing commands, and coding conventions. Check the -relevant component directory before starting work. +- **Ask first:** adding a dependency, changing public APIs, changes + that span more than one component, destructive git operations. +- **Never:** push to `upstream`, hand-edit generated files, commit + secrets or credentials, ping maintainers. ## Further Resources +- [CONTRIBUTING.md](CONTRIBUTING.md) - [New Contributor's Guide](https://arrow.apache.org/docs/developers/guide/index.html) - [Contributing Overview](https://arrow.apache.org/docs/developers/overview.html) -- [CONTRIBUTING.md](CONTRIBUTING.md) From f890e447dc6b321c4af998144d6a62d9f063d5a2 Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Tue, 27 Oct 2026 18:21:45 +0000 Subject: [PATCH 7/9] Update based on analysis of past PRs --- AGENTS.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 87 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e8b8427ad9f3..2607024eea3c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,6 +39,9 @@ closest file to the code you are editing takes precedence. - Generated files are committed and must not be hand-edited: `r/R/arrowExports.R` and `r/src/arrowExports.cpp` (regenerated by `r/data-raw/codegen.R`), and everything under `cpp/src/generated/`. +- C++ has two build systems. A file added to or removed from a + `CMakeLists.txt` usually needs the same change in the sibling + `meson.build`. - Every new source file needs the Apache License 2.0 header. Copy it from an existing file in the same directory. CI's license check (`rat`) rejects files without one. @@ -55,8 +58,12 @@ component before building, rather than guessing: - Running tests, per component: `docs/source/developers/guide/step_by_step/testing.rst` -Run the relevant tests locally before opening a PR, and run pre-commit -on the files you changed: +Build and run the affected tests locally before pushing. CI is not a +substitute: it is slow, shared, and reviewers notice when a test was +never compiled. Enable GitHub Actions on your fork to see CI results +before opening a PR. + +Run pre-commit on the files you changed: ```bash pip install pre-commit @@ -66,13 +73,48 @@ pre-commit run --all-files r # one component; aliases are listed in .pre- pre-commit run -a # every hook ``` +### Writing Tests + +- One test per behaviour. Fold near-identical cases into one test + with a loop or `parametrize` rather than copying the function. +- A regression test must fail without the fix. Check this before + pushing. +- Don't duplicate C++ test coverage in Python or R; binding tests + only need to show the plumbing works. +- Don't test compute kernels on invalid arrays (they are only + specified for valid input), and don't test type variants that share + a code path. Errors the code raises on purpose still need a test. +- Call `ValidateFull()` on arrays a C++ test builds. + +## Writing Code + +- Fix what the issue describes, nothing more. Don't generalise, rename, + or reformat nearby code, and keep unrelated files out of the diff. +- Internal preconditions are documented (or `DCHECK`ed), not validated + with error paths. Reviewers reject input validation nobody asked for. +- Before writing a bitmap loop, a visitor, an index normaliser, or a + test helper, look for an existing one in `cpp/src/arrow/util/` and + the nearest `testing/` or `test_util` file. There usually is one. +- Comments describe the code for a future reader, never the PR, the + bug, or what changed. If a comment says "this change", "now", + "still", or "previously", delete it or move it to the PR description. + A bare `// GH-12345` above a regression test is fine. +- Performance claims need numbers: put local benchmark results in the + PR description, and note there if a CI benchmark run would help. A + maintainer can trigger one. + ## Git - `upstream` is `apache/arrow`; `origin` is the contributor's fork. Fetch from `upstream`, push branches to `origin`, and check `git remote -v` before pushing. Never push to `upstream`. +- Never open a PR from your fork's `main` branch. Fork-sync bots + overwrite it, which empties the PR. - PRs are squash-merged, so the PR title and description become the commit message. Spend effort there rather than on individual commits. +- Rebase on `upstream/main` when the branch is stale, and force-push + your own PR branch; reviewers expect that. An outdated branch makes + CI run every job and often fails for unrelated reasons. ## Issues @@ -82,6 +124,12 @@ pre-commit run -a # every hook only, where it refers to the issue being fixed. - Search existing issues before creating one, and use the templates in `.github/ISSUE_TEMPLATE/`. +- Before starting on an issue, check that nobody is assigned and no PR + already exists for it. +- One issue per PR, but one issue for all instances of the same + pattern. Fix them together rather than opening a PR per file. +- If working on the fix changes your understanding of the bug, update + the issue description too. ## Pull Requests @@ -93,6 +141,9 @@ GH-: [Component] Short description Example: `GH-14736: [C++][Python] Ensure no validity bitmap in UnionArray::SetData` +Use the issue number, not the PR number, and match the component +casing of existing PRs (`[Docs]`, `[Format]`, `[C++]`). + A PR may use `MINOR: [Component] Short description` instead, with no issue, only if it is a grammar, usage, or spelling fix touching at most 2 files, or a documentation update touching at most 2 files and @@ -103,10 +154,24 @@ Fill in every section of `.github/pull_request_template.md`: - Keep each section to a sentence or two. Do not restate what the diff already shows. +- Do not draft the PR description. The contributor writes it, in + their own words, and updates it when the code changes so it still + matches what is in the PR. - Delete the "breaking changes" and "Critical Fix" lines unless they - genuinely apply. + genuinely apply. "Critical" is defined in the template (security, + incorrect data, or a crash), not any bug fix. - Complete the "Was AI used for this PR?" checkboxes truthfully, including who reviewed the change before submission. +- Don't `@mention` people in the description. It becomes the commit + message, so mentions follow it into git history and every + cherry-pick. + +Prefer one open PR at a time until your first is merged. Address +review feedback on an open PR before opening another; maintainers +close new PRs from authors who are ignoring feedback on old ones. + +After opening: fix CI failures your change caused. For failures that +are already happening on `main`, say so in a comment and leave them. ## Working with AI Tools @@ -114,20 +179,31 @@ Arrow's policy on AI-generated contributions is in `docs/source/developers/overview.rst` under "AI-generated code". In practice: -- A human reviews every change locally, understands it, and is - accountable for the PR. Do not open a PR or post to GitHub without - that review. -- Anything an agent drafts that is posted to GitHub (PR descriptions, - comments, reviews) must say so, in the template's disclosure section - or in a short attribution line at the end of the message. -- Never tag or ping maintainers. +- The contributor reviews every change locally, understands it, and + is accountable for the PR. Do not open a PR or post anything to + GitHub on their behalf without that review. Where the contributor + does not fully understand a part of the change, the policy asks + them to say so in a comment on the PR and explain how they verified + it; prompt them to do that rather than papering over it. +- Do not reply to review comments on the contributor's behalf, and do + not draft replies for them to paste. The contributor reads each + comment and answers it in their own words. Reviewers recognise + agent-written replies and treat them as a sign nobody is reading. + If the contributor has you draft any other GitHub post (an issue, + say), it must end with a short attribution line saying so. +- Do not report a review comment as addressed until the change is + pushed and visible in the diff. A claimed-but-missing change ends + the conversation. +- Never tag or ping maintainers, and never "bump" a PR. - Keep PRs small and focused. Avoid verbose comments, unnecessary test cases, and changes outside the scope of the issue. ## Boundaries - **Ask first:** adding a dependency, changing public APIs, changes - that span more than one component, destructive git operations. + that span more than one component, destructive git operations + (force-pushing the contributor's own PR branch after a rebase is + the one routine exception). - **Never:** push to `upstream`, hand-edit generated files, commit secrets or credentials, ping maintainers. From 45e28f49b0bf22e62a9c94e82c2e8bb828f9637d Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Tue, 27 Oct 2026 18:30:49 +0000 Subject: [PATCH 8/9] tell ppl how to run benchmarks --- AGENTS.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2607024eea3c..48b2b27c68b4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,9 +59,10 @@ component before building, rather than guessing: `docs/source/developers/guide/step_by_step/testing.rst` Build and run the affected tests locally before pushing. CI is not a -substitute: it is slow, shared, and reviewers notice when a test was -never compiled. Enable GitHub Actions on your fork to see CI results -before opening a PR. +substitute for a component's unit tests: it is slow and shared, and a +test that was never compiled is the first thing a reviewer sees. If +you cannot build the component, enable GitHub Actions on your fork +and don't open the PR until the jobs your change touches pass there. Run pre-commit on the files you changed: @@ -99,9 +100,13 @@ pre-commit run -a # every hook bug, or what changed. If a comment says "this change", "now", "still", or "previously", delete it or move it to the PR description. A bare `// GH-12345` above a regression test is fine. -- Performance claims need numbers: put local benchmark results in the - PR description, and note there if a CI benchmark run would help. A - maintainer can trigger one. +- Performance claims need numbers. For C++, run + `archery benchmark diff --benchmark-filter= HEAD upstream/main` + (see `docs/source/developers/benchmarks.rst`) and paste the table + into the PR description. Pass the baseline explicitly: the default + is `origin/HEAD`, which is the fork, not `apache/arrow`. A + maintainer can also trigger the CI benchmark run; note in the + description if that would help. ## Git From 96d331923fd643692afe3c1a9db3c9c63705a9fa Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Tue, 27 Oct 2026 18:38:12 +0000 Subject: [PATCH 9/9] Apply suggestion from @thisisnic --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 48b2b27c68b4..bbfeddb250b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,7 +33,7 @@ closest file to the code you are editing takes precedence. dependent bindings when you touch C++. - Java, Go, Rust, C#, JavaScript, Swift, and Julia are **not** in this repository. They live in `apache/arrow-java`, `apache/arrow-go`, - `apache/arrow-rs`, `apache/arrow-csharp`, `apache/arrow-js`, + `apache/arrow-rs`, `apache/arrow-dotnet`, `apache/arrow-js`, `apache/arrow-swift`, and `apache/arrow-julia`. Do not look for or recreate them here. - Generated files are committed and must not be hand-edited: