GH-50373: [Dev][Developer Tools] Add root AGENTS.md file by thisisnic · Pull Request #50375 · apache/arrow

thisisnic · 2026-07-05T14:11:02Z

Rationale for this change

Help AI agents produce better PRs and conform to workflows

What changes are included in this PR?

Add AGENTS.md file at project root

Are these changes tested?

No

Are there any user-facing changes?

No

GitHub Issue: [Dev][Developer Tools] Add root AGENTS.md file #50373

Copilot

Pull request overview

Adds a repository-root AGENTS.md to provide AI coding agents with shared, non-language-specific contribution workflow guidance for Apache Arrow.

Changes:

Introduces AGENTS.md with a high-level repository layout overview.
Documents Arrow’s issue/PR title conventions (including GH-<id>: vs MINOR:).
Links to pre-commit usage, testing guidance, and AI-generated code policy resources.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

rok

I don't have experience writing AGENTS.md files. A couple of things that I'd like agents be good at for myself:

setting up their own dev environment and not changing mine. But sometimes I'd want to use theirs.
building implementations (e.g. C++ and R) so they can run tests
running banchmarks

As per my experience they can already do these tasks, they are just not always consistent about it.

pitrou · 2026-07-08T09:17:12Z

Can we instead suggest that PRs should never be opened automatically by AI? Instead have the human review changes locally and write a proper description themselves?

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

+### 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:
+


Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.

+| 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) |
+


+pre-commit run -a                        # all hooks
+pre-commit run --all-files <hook-alias>   # e.g. python, cpp (see aliases in .pre-commit-config.yaml)


thisisnic · 2026-07-13T08:33:38Z

Can we instead suggest that PRs should never be opened automatically by AI? Instead have the human review changes locally and write a proper description themselves?

I think "never" might be a little strong here, e.g. I find it useful to have Claude open PRs for me (though only when I tell it) when I understand the change but would find it hard to describe in words or do a worse job of it; example: #50488

How about we adopt the convention that Airflow uses:

Anything an agent drafts that ends up posted to GitHub on the user's account — PR / issue comments, PR-level reviews, line-level review comments, discussion replies — must end with an attribution footer. The footer is required whether or not a human reviewed the draft first; what changes between the two cases is the wording.

This would allows us to differentiate between things which have been checked/reviewed by humans or not. You could also submit a PR to update the AI guidance, generally and for new contributors specifically as well?

Add generic AGENTS.md file

3ad017f

Copilot AI review requested due to automatic review settings July 5, 2026 14:11

Copilot started reviewing on behalf of thisisnic July 5, 2026 14:11 View session

github-actions Bot added Component: Documentation awaiting committer review Awaiting committer review labels Jul 5, 2026

Copilot AI reviewed Jul 5, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

thisisnic mentioned this pull request Jul 6, 2026

[Dev] Make PRs that doesn't match our PR format draft automatically #50379

Closed

Potential fix for pull request finding

4c7cd0b

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 6, 2026 15:50

Copilot started reviewing on behalf of thisisnic July 6, 2026 15:50 View session

Copilot AI reviewed Jul 6, 2026

View reviewed changes

Comment thread AGENTS.md

Comment thread AGENTS.md Outdated

rok reviewed Jul 6, 2026

View reviewed changes

Comment thread AGENTS.md

Comment thread AGENTS.md Outdated

github-actions Bot added awaiting changes Awaiting changes and removed awaiting committer review Awaiting committer review labels Jul 6, 2026

Update AGENTS file with feedback in mind

ff53a30

Copilot AI review requested due to automatic review settings July 9, 2026 11:43

github-actions Bot added awaiting change review Awaiting change review and removed awaiting changes Awaiting changes labels Jul 9, 2026

Copilot started reviewing on behalf of thisisnic July 9, 2026 11:44 View session

Enhance phrasing

00d0a5b

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread AGENTS.md

Comment thread AGENTS.md

Comment on lines +88 to +93

### 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:

Copilot AI review requested due to automatic review settings July 9, 2026 11:46

Copilot started reviewing on behalf of thisisnic July 9, 2026 11:47 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Potential fix for pull request finding

2a09a5e

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings July 9, 2026 11:50

Copilot started reviewing on behalf of thisisnic July 9, 2026 11:51 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

github-actions Bot removed the awaiting change review Awaiting change review label Jul 9, 2026

github-actions Bot added the awaiting changes Awaiting changes label Jul 9, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

GH-50373: [Dev][Developer Tools] Add root AGENTS.md file#50375

GH-50373: [Dev][Developer Tools] Add root AGENTS.md file#50375
thisisnic wants to merge 5 commits into
apache:mainfrom
thisisnic:GH-50373-agents-at-root

thisisnic commented Jul 5, 2026 •

edited by github-actions Bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

rok left a comment

Uh oh!

Uh oh!

Uh oh!

pitrou commented Jul 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

thisisnic commented Jul 13, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		pre-commit run -a # all hooks
		pre-commit run --all-files <hook-alias> # e.g. python, cpp (see aliases in .pre-commit-config.yaml)

Uh oh!

Conversation

thisisnic commented Jul 5, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rationale for this change

What changes are included in this PR?

Are these changes tested?

Are there any user-facing changes?

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

rok left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

pitrou commented Jul 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

thisisnic commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

thisisnic commented Jul 5, 2026 •

edited by github-actions Bot

Loading

thisisnic commented Jul 13, 2026 •

edited

Loading