How to contribute

This section covers how work gets picked up, reviewed, and merged in this repository. The official New Contributor's Guide at https://arrow.apache.org/docs/developers/guide/index.html is the canonical reference; this section summarizes the parts most relevant to navigating the Arrow source tree.

How work flows

graph LR
    Issue["1. GitHub issue (or 'take' an existing one)"] --> Branch["2. Fork + branch"]
    Branch --> Develop["3. Develop + run local tests"]
    Develop --> PR["4. Open PR with 'GH-NNN: [Component] Title' prefix"]
    PR --> CI["5. CI matrix runs (cpp, python, r, ruby, c_glib, matlab, integration)"]
    CI --> Review["6. Review by component maintainers"]
    Review --> Merge["7. Committer merges via dev/merge_arrow_pr.py"]

Issues

The Arrow project uses GitHub Issues as its bug tracker. Conventions:

• Issue titles are prefixed with the component in brackets, e.g. [C++][Python] Ensure no validity bitmap in UnionArray::SetData.
• A contributor "claims" an issue by commenting take. The .github/workflows/issue_bot.yml workflow automates the assignment.
• Bug reports and enhancement requests use templates under .github/ISSUE_TEMPLATE/.

Pull requests

Pull request titles follow the form GH-<issue>: [Component] Title (#PR). The merge tool (dev/merge_arrow_pr.py) enforces this format. For tiny doc-only or grammar fixes, the prefix MINOR: is allowed and no issue is required.

CI workflows in .github/workflows/ run automatically. Required checks include the relevant component build (cpp.yml, python.yml, r.yml, ruby.yml, matlab.yml, c_glib jobs in cpp.yml) and integration jobs (integration.yml, dev.yml). The PR bot in .github/workflows/pr_bot.yml adds labels and posts links to crossbow runs when a maintainer comments @github-actions crossbow submit ....

Definition of done

Maintainers expect a PR to:

1. Build cleanly on all relevant platforms (CI).
2. Carry tests for the change. Most subsystems have a paired *_test.cc (C++) or test_*.py (Python). Adding to those is the convention.
3. Update changelogs only via the release process — CHANGELOG.md is generated from issue/PR metadata at release time, not edited by hand.
4. Pass the project's lint and format checks (clang-format, cpplint, ruff, lintr, rubocop, hadolint, shellcheck — all configured at the repo root).
5. Avoid breaking ABI on minor releases; ABI changes need maintainer sign-off.

Development workflow per component

Each language wrapper has its own dev loop. See:

• Development workflow — branch, build, run tests for a particular component.
• Testing — frameworks, fixtures, integration tests.
• Debugging — debugger setup, gdb pretty-printers, common failure modes.
• Patterns and conventions — error handling, async, naming.
• Tooling — the archery CLI, lint/format scripts, Docker compose setup.

Communicating

Big design changes happen on the arrow-dev mailing list. Day-to-day discussion happens on issues and PRs. Apache Arrow is governed by the Apache Software Foundation Code of Conduct; see CODE_OF_CONDUCT.md.