From 3ad017f7fb40bb2674e595fa1614d33dddf70528 Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Sun, 5 Jul 2026 15:08:53 +0100 Subject: [PATCH 1/5] 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 00000000000..1a80942bbb1 --- /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 4c7cd0ba3892d7b559a0a8f2e4737dc24715fd45 Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Mon, 6 Jul 2026 16:50:03 +0100 Subject: [PATCH 2/5] 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 1a80942bbb1..45b1d598552 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 ff53a303f767777960069aba436fc52954ab5355 Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Thu, 9 Jul 2026 12:43:34 +0100 Subject: [PATCH 3/5] 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 45b1d598552..20d1a7f052e 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 00d0a5b4488156b288fb5a701e5713ad7b28177d Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Thu, 9 Jul 2026 12:46:22 +0100 Subject: [PATCH 4/5] Enhance phrasing --- AGENTS.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 20d1a7f052e..7785ad36357 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 2a09a5ee0a79b0715eb42fef53bde1ed265b7bbc Mon Sep 17 00:00:00 2001 From: Nic Crane Date: Thu, 9 Jul 2026 12:50:48 +0100 Subject: [PATCH 5/5] 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 7785ad36357..12eff43d2b7 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