Context

There is no written procedure for bumping the supported PyArrow version in PyMongoArrow. The recipe currently only exists as knowledge spread across past PRs/tickets (INTPYTHON-889 for PyArrow 23, INTPYTHON-969 for 24, INTPYTHON-1016 for 25). RELEASE.md covers cutting a release generally but says nothing PyArrow-specific, and CONTRIBUTING.md has no upgrade section.

The C extension (pymongoarrow/lib) links directly against PyArrow's C++ shared libraries (see CMakeLists.txt: PyArrow include dir, get_libraries(), and create_library_symlinks()). PyArrow does not guarantee a stable C++ ABI across minor versions, so each wheel is bound to exactly one PyArrow minor. That is why the pin is narrow (>=X.0,[X.1) and why every bump drops the previous minor. This rationale is undocumented.

Definition of done

• Add an "Upgrading PyArrow" section (in CONTRIBUTING.md, or a dedicated doc) covering:
  • Check the Apache Arrow release notes (https://arrow.apache.org/release/<version].html) for anything touching the C++/C-data ABI or Python type APIs.
  • Bump both pins in pyproject.toml and keep them in sync: [build-system].requires and [project].dependencies (both >=X.0,<X.1).
  • Regenerate the lockfile with uv lock.
  • Add a CHANGELOG entry in the form: "Add support for PyArrow X.0. Drop support for PyArrow (X-1).0."
  • Note the ABI-coupling rationale so the narrow pin / mandatory drop is not surprising to future maintainers.

Pitfalls

NA