Release Process

This guide provides comprehensive information on the Apache Arrow release process. It serves as both a learning resource and a detailed checklist for Release Managers performing releases.

The Release Manager must have at least committer status. Some tasks require PMC membership and are marked accordingly throughout this guide.

Overview

The Apache Arrow release follows the Apache Software Foundation Release Policy.

Release Principles

Releases are created from maintenance branches
Feature freeze occurs when the maintenance branch is created
Only bug fixes are accepted after feature freeze (unless community consensus allows an exception)
Issues labeled as blocker must be resolved before creating a release candidate
Pull requests are voted on by the PMC, requiring a net of 3 +1 votes from PMC members

Prerequisites

Required Tools and Access

Install Archery utility: pip install -e dev/archery
Build requirements for C++ and C GLib installed
en_US.UTF-8 locale installed (verify with locale -a)
Python 3 installed as python
Docker and Docker Compose installed
GitHub CLI (gh) installed
Crossbow configured

GPG Key Setup

You need a GPG key in the Apache Web of Trust to sign artifacts.

Set default GPG key

If you have multiple GPG keys, set the correct one in ~/.gnupg/gpg.conf:

default-key ${YOUR_GPG_KEY_ID}

Add key to SVN repositories

Add your GPG key to both:

(Requires PMC membership)

Setup GPG agent

source dev/release/setup-gpg-agent.sh

Environment Configuration

Create dev/release/.env from dev/release/.env.example and configure the variables as described in the example file.

Build Environment

No Arrow environment variables should be defined except CC or CXX if building with a specific compiler
Ensure you have adequate RAM:
- Minimal build: 1GB
- Minimal debug build with tests: 4GB
- Full build: 8GB

Preparing for a Release

Communicate with the community

In advance of the release date, announce the upcoming release via:

Zulip
Mailing list
Bi-weekly community call

Propose a feature freeze date when the maintenance branch will be created.

Create feature freeze

After feature freeze, no new features are allowed unless there’s community consensus. Only bug fixes will be accepted.

Resolve blockers

All issues labeled blocker must be resolved before creating the first release candidate.

Ensure proper milestones

Verify that resolved GitHub issues have the appropriate milestone set for proper changelog generation:

archery release curate <version>

The report shows any issues with incorrect version numbers.

Create next milestone

Ensure a major version milestone for the follow-up release exists on GitHub. This is automatically used by the merge script.

Creating a Release Candidate

Initial Release Candidate

For the first RC of a major release, create a maintenance branch from main.

Clean up local environment

# Delete any existing local tags
git tag -d apache-arrow-<version>

# Setup GPG agent
source dev/release/setup-gpg-agent.sh

Create maintenance branch

# Execute from an up-to-date main branch
# This creates a branch called maint-X.Y.Z locally
# X.Y.Z = Major.Minor.Patch (e.g., 9.0.0)
archery release cherry-pick X.Y.Z --execute

# Push the maintenance branch
git push -u upstream maint-X.Y.Z

Create release candidate branch and tag

# Start from the maintenance branch
git checkout maint-X.Y.Z

# Create RC branch and tag
# <rc-number> starts at 0 (so first RC: 0)
# On macOS, install gnu-sed: brew install gnu-sed
dev/release/01-prepare.sh <version> <next-version> <rc-number>

# Example: dev/release/01-prepare.sh 9.0.0 10.0.0 0

# Push the RC tag
git push -u upstream apache-arrow-<version>-rc<rc-number>

# Push the RC branch (triggers verification jobs)
git push -u upstream release-<version>-rc<rc-number>

This triggers GitHub Actions workflows:

verify-rc.yml: Verifies the release candidate
release_candidate.yml: Signs source code and creates a GitHub pre-release

Build and submit binaries

# Upload source and signatures to SVN (requires PMC member)
dev/release/02-source.sh <version> <rc-number>

# Submit binary tasks using Crossbow
dev/release/03-binary-submit.sh <version> <rc-number>
# Note the crossbow-build-id from output

# Wait for Crossbow jobs to finish
archery crossbow status <crossbow-build-id>

# Download produced binaries
dev/release/04-binary-download.sh <version> <rc-number>

# Sign and upload binaries (requires PMC member)
dev/release/05-binary-upload.sh <version> <rc-number>

# Sign and upload MATLAB artifacts (requires PMC member)
dev/release/06-matlab-upload.sh <version> <rc-number>

# Publish GitHub Release
dev/release/07-publish-gh-release.sh <version> <rc-number>

# Start binary verification
dev/release/08-binary-verify.sh <version> <rc-number>

Start the vote

Once automatic verification passes, start the vote thread on dev@arrow.apache.org:

# Generate email template
SOURCE_DEFAULT=0 SOURCE_VOTE=1 dev/release/02-source.sh <version> <rc-number>

Voting requires:

Net of 3 +1 votes from PMC members
Vote open for at least 72 hours
Cannot be vetoed

Follow-up Release Candidates

If issues are found during verification:

Update maintenance branch

# Dry-run to see which commits will be cherry-picked
archery release cherry-pick X.Y.Z --continue

# Update the maintenance branch
archery release cherry-pick X.Y.Z --continue --execute

# Push updates
git push -u upstream maint-X.Y.Z

Create new RC

Repeat the RC creation steps with an incremented <rc-number> (e.g., 1, 2, 3…).

Patch Releases

Patch releases are created for major breaking issues like security fixes or broken packages.

Request patch release

Any developer can request a patch release by emailing dev@arrow.apache.org with the reason. Consensus and a willing Release Manager are required.

Tag issues for backport

Committers tag issues for the next patch release using the backport-candidate label.

Create patch release checklist

Create milestone
Create maintenance branch from previous release
Include the issue requiring the patch
Add new milestone to issues with backport-candidate label
Cherry-pick issues into maintenance branch

Follow RC process

Follow the standard RC creation process for the patch release.

Post-Release Tasks

After the release vote passes, complete these tasks:

Update milestone

Set the milestone date on GitHub
Mark milestone as “Closed”

Merge release branch (patches only)

For patch releases, merge the release branch to maintenance:

git checkout maint-X.Y.Z
git merge release-X.Y.Z-rcN
git push -u upstream maint-X.Y.Z

Push release tag

dev/release/post-01-tag.sh <version> <rc-number>

Upload to Subversion (PMC)

dev/release/post-02-upload.sh <version> <rc-number>

Upload binaries to Artifactory

dev/release/post-03-binary.sh <version> <rc-number>

Update website

# Prepare arrow-site fork (one-time setup)
git clone git@github.com:<YOUR_GITHUB_ID>/arrow-site.git ../arrow-site
cd ../arrow-site
git remote add upstream git@github.com:apache/arrow-site.git
cd -

# Generate release note and update latest release info
dev/release/post-04-website.sh <OLD_VERSION> <NEW_VERSION>

This creates a branch in your fork. Open a PR from that branch.

Update GitHub Release Notes

After the website PR merges:

dev/release/post-05-update-gh-release-notes.sh <version>

Update package managers

Homebrew
MSYS2
vcpkg
Conan

# One-time setup
cd "$(brew --repository homebrew/core)"
git remote add <YOUR_GITHUB_ID> git@github.com:<YOUR_GITHUB_ID>/homebrew-core.git
cd -

# Update Homebrew
dev/release/post-12-homebrew.sh <version> <YOUR_GITHUB_ID>

Open PR with title: apache-arrow, apache-arrow-glib: X.Y.Z

# One-time setup
git clone git@github.com:<YOUR_GITHUB_ID>/MINGW-packages.git ../MINGW-packages
cd ../MINGW-packages
git remote add upstream https://github.com/msys2/MINGW-packages.git
cd -

# Update MSYS2
dev/release/post-11-msys2.sh <version> ../MINGW-packages

Open PR with title: arrow: Update to X.Y.Z

# One-time setup
git clone git@github.com:<YOUR_GITHUB_ID>/vcpkg.git ../vcpkg
cd ../vcpkg
./bootstrap-vcpkg.sh
git remote add upstream https://github.com/microsoft/vcpkg.git
cd -

# Update vcpkg
dev/release/post-13-vcpkg.sh <version> ../vcpkg

Open PR with title: [arrow] Update to X.Y.Z

# One-time setup
git clone git@github.com:<YOUR_GITHUB_ID>/conan-center-index.git ../conan-center-index
cd ../conan-center-index
git remote add upstream https://github.com/conan-io/conan-center-index.git
cd -

# Update Conan
dev/release/post-14-conan.sh <version> ../conan-center-index

Open PR on your browser

Upload to package repositories

RubyGems
PyPI
CRAN (R)

Requires account on https://rubygems.org/ with owner permissions.To add new owners:

dev/release/account-ruby.sh <NEW_ACCOUNT>

Upload (after Homebrew and MSYS2 are updated):

dev/release/post-06-ruby.sh <version>

dev/release/post-09-python.sh <version>

Update documentation

# Prepare arrow-site fork if not already done
git clone git@github.com:<YOUR_GITHUB_ID>/arrow-site.git ../arrow-site
cd ../arrow-site
git remote add upstream git@github.com:apache/arrow-site.git
cd -

# Upload generated documentation
dev/release/post-08-docs.sh <NEW_VERSION> <OLD_VERSION>

Create PR targeting the asf-site branch.

Bump versions

dev/release/post-10-bump-versions.sh <VERSION> <NEXT_VERSION>

Set BUMP_TAG=0 and BUMP_PUSH=0 to review before pushing.

Update Arrow Cookbook

Follow the documentation in the Arrow Cookbook repository.

Announce the release

Write an announcement (see example) and send to:

announce@apache.org (must send from your @apache.org email)
dev@arrow.apache.org

Publish blog post

Clone https://github.com/apache/arrow-site
Create new branch for blog post PR
Duplicate recent blog post in _posts/
Update filename and YAML metadata with new release date (GMT)
Update content as needed
Create PR and request community help filling in details

Announce on social media

Post about the release on official accounts (PMC members have access):

BlueSky: @arrow.apache.org
LinkedIn: https://www.linkedin.com/company/apache-arrow/

Add to Apache Reporter

Add release data to Apache Reporter.

Remove old artifacts (PMC)

Remove RC artifacts and old releases per ASF policy:

dev/release/post-07-remove-old-artifacts.sh

Testing Before Release

Some Release Managers prefer testing before creating the first RC:

Create dummy PR

Create a PR from maint-X.Y.Z to main titled “WIP: Dummy PR to check maint-X.Y.Z status”.

Trigger Crossbow jobs

Comment on the PR:

@github-actions crossbow submit --group verify-rc-source
@github-actions crossbow submit --group packaging

Review results

Check that all jobs pass before creating the official RC.

Verification

See the Release Verification Guide for detailed steps on verifying:

Source release integrity
Binary package functionality
Signature verification
License compliance

Troubleshooting

GPG signing issues on macOS

If you get “ioctl” errors when signing:

echo "UPDATESTARTUPTTY" | gpg-connect-agent

Then retry the signing command.

Cherry-pick conflicts

If automated cherry-picking fails:

Manually cherry-pick the problematic commits
Resolve conflicts
Continue the release process
Note: PRs without corresponding GitHub issues must be cherry-picked manually

Crossbow failures

Check the Crossbow dashboard for specific job failures. Common issues:

Timeout: Rerun the job
Dependency version mismatch: Update the build scripts
Platform-specific build failure: May need architecture-specific fixes

Resources

ASF Release Policy

Official Apache Software Foundation release guidelines

Archery Utility

Arrow’s development and release management tool

Release Verification

Guide to verifying Arrow releases

Crossbow

Automated build and test system for releases

Contributing

Building from Source

Development

Overview

Release Principles

Prerequisites

Preparing for a Release

Creating a Release Candidate

Initial Release Candidate

Follow-up Release Candidates

Patch Releases

Post-Release Tasks

Testing Before Release

Verification

Troubleshooting

Resources

ASF Release Policy

Archery Utility

Release Verification

Crossbow

Build docs developers (and LLMs) love

Contributing

Building from Source

Development

​Overview

​Release Principles

​Prerequisites

​Preparing for a Release

​Creating a Release Candidate

​Initial Release Candidate

​Follow-up Release Candidates

​Patch Releases

​Post-Release Tasks

​Testing Before Release

​Verification

​Troubleshooting

​Resources

ASF Release Policy

Archery Utility

Release Verification

Crossbow

Build docs developers (and LLMs) love

Overview

Release Principles

Prerequisites

Preparing for a Release

Creating a Release Candidate

Initial Release Candidate

Follow-up Release Candidates

Patch Releases

Post-Release Tasks

Testing Before Release

Verification

Troubleshooting

Resources