You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by "thisisnic (via GitHub)" <gi...@apache.org> on 2026/07/05 14:11:04 UTC

[PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

thisisnic opened a new pull request, #50375:
URL: https://github.com/apache/arrow/pull/50375

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


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on PR #50375:
URL: https://github.com/apache/arrow/pull/50375#issuecomment-4913276067

   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?


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "thisisnic (via GitHub)" <gi...@apache.org>.
thisisnic commented on PR #50375:
URL: https://github.com/apache/arrow/pull/50375#issuecomment-4955998308

   > 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 bit 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: https://github.com/apache/arrow/pull/50488
   
   How about we adopt [the convention that Airflow uses](https://github.com/apache/airflow/blob/main/AGENTS.md):
   
   > 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.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "thisisnic (via GitHub) via github" <gi...@arrow.apache.org>.
thisisnic commented on PR #50375:
URL: https://github.com/apache/arrow/pull/50375#issuecomment-6611407505

   > This is very wordy, do we except to maintain this by hand?
   
   It's the typical length of these things, but I'll look to trim out any verbose language etc.  Will grab some similar repos examples to compare.  Happy to own maintenance of this myself.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #50375:
URL: https://github.com/apache/arrow/pull/50375#discussion_r3551363810


##########
AGENTS.md:
##########
@@ -0,0 +1,155 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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) |
+

Review Comment:
   The repository layout table uses `||` at the start of each row, which renders as an extra empty column in standard Markdown table syntax. Use single `|` delimiters so the table renders correctly on GitHub.



##########
AGENTS.md:
##########
@@ -0,0 +1,155 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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)
+
+## 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
+
+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
+
+- 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.
+
+## Pull Request Conventions
+
+### Title Format
+
+```
+GH-<issue-number>: [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 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.
+
+### 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 <hook-alias>   # e.g. python, cpp (see aliases in .pre-commit-config.yaml)

Review Comment:
   The `pre-commit run --all-files <hook-alias>` example is potentially misleading: pre-commit runs hooks by hook `id` (and aliases can be confusing here since multiple hooks share the same `alias`, e.g. `cpp`). Consider documenting invocation by hook id(s) instead and referencing `.pre-commit-config.yaml`.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "thisisnic (via GitHub) via github" <gi...@arrow.apache.org>.
thisisnic commented on code in PR #50375:
URL: https://github.com/apache/arrow/pull/50375#discussion_r4458450373


##########
AGENTS.md:
##########
@@ -0,0 +1,219 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# AGENTS.md
+
+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-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:
+  `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.
+
+## 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`
+
+Build and run the affected tests locally before pushing. CI is not a
+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:
+
+```bash
+pip install pre-commit
+pre-commit install
+pre-commit run --files <paths you changed>
+pre-commit run --all-files r        # one component; aliases are listed in .pre-commit-config.yaml
+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. For C++, run
+  `archery benchmark diff --benchmark-filter=<name> 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
+
+- `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
+
+- 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/`.

Review Comment:
   I don't think we should ban it outright - I use it for describing CI failures and think it does a good job of it. But perhaps for bugs and feature requests, we could get it to ask the user to describe how they were affected in their own words?
   
   What do poorly-crafted agent-created issues look like? I'm thinking too much information, complex descriptions; anything else, @pitrou?



##########
AGENTS.md:
##########
@@ -0,0 +1,219 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# AGENTS.md
+
+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-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:
+  `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.
+
+## 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`
+
+Build and run the affected tests locally before pushing. CI is not a
+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.

Review Comment:
   Oops, I'll change



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "rok (via GitHub)" <gi...@apache.org>.
rok commented on code in PR #50375:
URL: https://github.com/apache/arrow/pull/50375#discussion_r3531135330


##########
AGENTS.md:
##########
@@ -0,0 +1,128 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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
+

Review Comment:
   Should we link to [PR template](https://github.com/apache/arrow/blob/main/.github/pull_request_template.md) here instead? I suppose it's better for agents to have the .md file here, just noting a thought.



##########
AGENTS.md:
##########
@@ -0,0 +1,128 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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:

Review Comment:
   Similar to below - should we link to our [issue templates](https://github.com/apache/arrow/tree/main/.github/ISSUE_TEMPLATE)?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #50375:
URL: https://github.com/apache/arrow/pull/50375#discussion_r4392572237


##########
AGENTS.md:
##########
@@ -0,0 +1,214 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# AGENTS.md
+
+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`,

Review Comment:
   The C# implementation lives in `apache/arrow-dotnet`, as linked in `README.md:46` and `docs/source/implementations.rst:39`, not `apache/arrow-csharp`. Please use the correct repository name so agents following this routing guidance can locate the implementation.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "thisisnic (via GitHub)" <gi...@apache.org>.
thisisnic commented on code in PR #50375:
URL: https://github.com/apache/arrow/pull/50375#discussion_r3551748778


##########
AGENTS.md:
##########
@@ -0,0 +1,145 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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)
+
+## 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
+
+- 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.

Review Comment:
   Nope, this is correcting common agent mistakes



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "thisisnic (via GitHub)" <gi...@apache.org>.
thisisnic commented on PR #50375:
URL: https://github.com/apache/arrow/pull/50375#issuecomment-6450239726

   I've updated this in line with some feedback + also doing a quick analysis of common feedback on PRs from first time contributors across the past 6 months.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #50375:
URL: https://github.com/apache/arrow/pull/50375#discussion_r3525038384


##########
AGENTS.md:
##########
@@ -0,0 +1,128 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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-<issue-number>: [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 <component>   # single component (alias from .pre-commit-config.yaml)

Review Comment:
   The argument to `pre-commit run` is a hook id/alias, not necessarily a repository “component”. Using `<component>` here is misleading (e.g., `.pre-commit-config.yaml` defines aliases like `python`, `cpp`, `docker`, etc.). Consider renaming the placeholder to reflect what users should actually pass.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #50375:
URL: https://github.com/apache/arrow/pull/50375#discussion_r3530240948


##########
AGENTS.md:
##########
@@ -0,0 +1,128 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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) |
+

Review Comment:
   The markdown table has an extra leading `|` on each row (`|| ...`), which renders as an empty first column on GitHub. Use standard table syntax with a single leading pipe per row.



##########
AGENTS.md:
##########
@@ -0,0 +1,128 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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.

Review Comment:
   The issue-title guidance is more strict than (and not supported by) the project's CONTRIBUTING.md, which only documents the component-prefix convention. Consider softening this to a descriptive note instead of a hard "Do NOT" rule.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "thisisnic (via GitHub)" <gi...@apache.org>.
thisisnic commented on code in PR #50375:
URL: https://github.com/apache/arrow/pull/50375#discussion_r3543006202


##########
AGENTS.md:
##########
@@ -0,0 +1,128 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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
+

Review Comment:
   Sounds good



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #50375:
URL: https://github.com/apache/arrow/pull/50375#discussion_r3551327738


##########
AGENTS.md:
##########
@@ -0,0 +1,145 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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)
+
+## 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
+
+- 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.
+
+## Pull Request Conventions
+
+### Title Format
+
+```
+GH-<issue-number>: [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:
+

Review Comment:
   The MINOR criteria here are slightly different from CONTRIBUTING.md: the 500-word limit applies to documentation updates, but grammar/usage/spelling fixes only need to be limited to 2 files (no word-count constraint is documented). Aligning this text avoids conflicting guidance.



##########
AGENTS.md:
##########
@@ -0,0 +1,145 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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)
+
+## 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
+
+- 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.

Review Comment:
   The issue-title guidance here doesn’t match the documented convention in CONTRIBUTING.md (issue titles should be prefixed with component(s) in brackets). Consider updating this section to reflect the established `[Component]` convention and avoid introducing an undocumented rule.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #50375:
URL: https://github.com/apache/arrow/pull/50375#discussion_r3551342171


##########
AGENTS.md:
##########
@@ -0,0 +1,157 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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)
+
+## 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
+
+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
+
+- 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.
+
+## Pull Request Conventions
+
+### Title Format
+
+```
+GH-<issue-number>: [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.

Review Comment:
   The repo’s PR title checker treats a PR as MINOR only when the title starts with `MINOR: ` (note the required space after the colon). Using `MINOR:` without the space can cause the title check workflow to fail; this also matches the wording in CONTRIBUTING.md.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "thisisnic (via GitHub)" <gi...@apache.org>.
thisisnic commented on code in PR #50375:
URL: https://github.com/apache/arrow/pull/50375#discussion_r4392694427


##########
AGENTS.md:
##########
@@ -0,0 +1,219 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# AGENTS.md
+
+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`,

Review Comment:
   ```suggestion
     `apache/arrow-rs`, `apache/arrow-dotnet`, `apache/arrow-js`,
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] GH-50373: [Dev][Developer Tools] Add root AGENTS.md file [arrow]

Posted by "pitrou (via GitHub)" <gi...@apache.org>.
pitrou commented on code in PR #50375:
URL: https://github.com/apache/arrow/pull/50375#discussion_r4410621509


##########
AGENTS.md:
##########
@@ -0,0 +1,219 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# AGENTS.md
+
+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-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:
+  `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.
+
+## 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`
+
+Build and run the affected tests locally before pushing. CI is not a
+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:
+
+```bash
+pip install pre-commit
+pre-commit install
+pre-commit run --files <paths you changed>
+pre-commit run --all-files r        # one component; aliases are listed in .pre-commit-config.yaml
+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. For C++, run
+  `archery benchmark diff --benchmark-filter=<name> 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
+
+- `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
+
+- 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/`.

Review Comment:
   Do we want agents to create issues?



##########
AGENTS.md:
##########
@@ -0,0 +1,219 @@
+<!---
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# AGENTS.md
+
+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-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:
+  `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.
+
+## 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`
+
+Build and run the affected tests locally before pushing. CI is not a
+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.

Review Comment:
   Agents should not open PRs by themselves, right?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org