Skip to main content
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

  • 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
You need a GPG key in the Apache Web of Trust to sign artifacts.
1

Set default GPG key

If you have multiple GPG keys, set the correct one in ~/.gnupg/gpg.conf:
default-key ${YOUR_GPG_KEY_ID}
2

Add key to SVN repositories

Add your GPG key to both:(Requires PMC membership)
3

Setup GPG agent

source dev/release/setup-gpg-agent.sh
Create dev/release/.env from dev/release/.env.example and configure the variables as described in the example file.
  • 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

1

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.
2

Create feature freeze

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

Resolve blockers

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

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.
5

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.
1

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
2

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
3

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
4

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

Start the vote

Once automatic verification passes, start the vote thread on [email protected]:
# 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:
1

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
2

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.
1

Request patch release

Any developer can request a patch release by emailing [email protected] with the reason. Consensus and a willing Release Manager are required.
2

Tag issues for backport

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

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
4

Follow RC process

Follow the standard RC creation process for the patch release.

​
Post-Release Tasks

After the release vote passes, complete these tasks:
1

Update milestone

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

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
3

Push release tag

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

Upload to Subversion (PMC)

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

Upload binaries to Artifactory

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

Update website

# Prepare arrow-site fork (one-time setup)
git clone [email protected]:<YOUR_GITHUB_ID>/arrow-site.git ../arrow-site
cd ../arrow-site
git remote add upstream [email protected]: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.
7

Update GitHub Release Notes

After the website PR merges:
dev/release/post-05-update-gh-release-notes.sh <version>
8

Update package managers

# One-time setup
cd "$(brew --repository homebrew/core)"
git remote add <YOUR_GITHUB_ID> [email protected]:<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
9

Upload to package repositories

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

Update documentation

# Prepare arrow-site fork if not already done
git clone [email protected]:<YOUR_GITHUB_ID>/arrow-site.git ../arrow-site
cd ../arrow-site
git remote add upstream [email protected]: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.
11

Bump versions

dev/release/post-10-bump-versions.sh <VERSION> <NEXT_VERSION>
Set BUMP_TAG=0 and BUMP_PUSH=0 to review before pushing.
12

Update Arrow Cookbook

Follow the documentation in the Arrow Cookbook repository.
13

Announce the release

Write an announcement (see example) and send to:
14

Publish blog post

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

Announce on social media

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

Add to Apache Reporter

Add release data to Apache Reporter.
17

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

Create dummy PR

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

Trigger Crossbow jobs

Comment on the PR:
@github-actions crossbow submit --group verify-rc-source
@github-actions crossbow submit --group packaging
3

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

If you get “ioctl” errors when signing:
echo "UPDATESTARTUPTTY" | gpg-connect-agent
Then retry the signing command.
If automated cherry-picking fails:
  1. Manually cherry-pick the problematic commits
  2. Resolve conflicts
  3. Continue the release process
  4. Note: PRs without corresponding GitHub issues must be cherry-picked manually
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

Build docs developers (and LLMs) love

Get started for freeTalk to us