Release Management Guide

This page provides detailed information on the steps followed to perform a release. It can be used both as a guide to learn the Apache Arrow release process and as a comprehensive checklist for the Release Manager when performing a release.

Principles

The Apache Arrow Release follows the guidelines defined at the Apache Software Foundation Release Policy.

Preparing for the release

Before creating a source release, the Release Manager must ensure that any resolved JIRAs have the appropriate Fix Version set so that the changelog is generated properly.

Requirements

Some steps of the release require being a committer or a PMC member.

  • Install the Archery utility which is required for the release.

  • You must not have any arrow-cpp or parquet-cpp environment variables defined except CC or CXX if you want to build with something other than GCC by default (e.g. clang).

  • A GPG key in the Apache Web of Trust to sign artifacts. This will have to be cross signed by other Apache committers/PMC members. If you have multiple GPG keys, you must set the correct GPG key ID in ~/.gnupg/gpg.conf by adding:

default-key ${YOUR_GPG_KEY_ID}
# You might need to export GPG_TTY=$(tty) to properly prompt for a passphrase
mvn clean install -Papache-release
  • Have the build requirements for cpp and c_glib installed.

  • Set the JIRA_USERNAME and JIRA_PASSWORD environment variables

  • Set the CROSSBOW_GITHUB_TOKEN environment variable to automatically create the verify release Pull Request.

  • Install en_US.UTF-8 locale. You can confirm available locales by locale -a.

  • Install Python 3 as python

  • Create dev/release/.env from dev/release/.env.example. See the comments in dev/release/.env.example how to set each variable.

  • Setup Crossbow as defined.

  • Have Docker and docker-compose installed.

Before creating a Release Candidate

Ensure local tags are removed, gpg-agent is set and JIRA tickets are correctly assigned.

# Delete the local tag for RC1 or later
git tag -d apache-arrow-<version>

# Setup gpg agent for signing artifacts
source dev/release/setup-gpg-agent.sh

# Curate the release
# The end of the generated report shows the JIRA tickets with wrong version number assigned.
archery release curate <version>

Creating a Release Candidate

These are the different steps that are required to create a Release Candidate.

For the initial Release Candidate, we will create a maintenance branch from master. Follow up Release Candidates will update the maintenance branch by cherry-picking specific commits.

We have implemented a Feature Freeze policy between Release Candidates. This means that, in general, we should only add bug fixes between Release Candidates. In rare cases, critical features can be added between Release Candidates, if there is community consensus.

Create or update the corresponding maintenance branch

# Execute the following from an up to date master branch.
# This will create a branch locally called maint-X.Y.Z.
# X.Y.Z corresponds with the Major, Minor and Patch version number
# of the release respectively. As an example 9.0.0
archery release --jira-cache /tmp/jiracache cherry-pick X.Y.Z --execute
# Push the maintenance branch to the remote repository
git push -u apache maint-X.Y.Z
# First run in dry-mode to see which commits will be cherry-picked.
# If there are commits that we don't want to get applied ensure the version on
# JIRA is set to the following release.
archery release --jira-cache /tmp/jiracache cherry-pick X.Y.Z --continue
# Update the maintenance branch with the previous commits
archery release --jira-cache /tmp/jiracache cherry-pick X.Y.Z --continue --execute
# Push the updated maintenance branch to the remote repository
git push -u apache maint-X.Y.Z

Create the Release Candidate branch from the updated maintenance branch

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

# The following script will create a branch for the Release Candidate,
# place the necessary commits updating the version number and then create a git tag
# on OSX use gnu-sed with homebrew: brew install gnu-sed (and export to $PATH)
#
# <rc-number> starts at 0 and increments every time the Release Candidate is burned
# so for the first RC this would be: dev/release/01-prepare.sh 4.0.0 5.0.0 0
dev/release/01-prepare.sh <version> <next-version> <rc-number>

# Push the release tag (for RC1 or later the --force flag is required)
git push -u apache apache-arrow-<version>
# Push the release candidate branch in order to trigger verification jobs later
git push -u apache release-<version>-rc<rc-number>

Build source and binaries and submit them

# Build the source release tarball and create Pull Request with verification tasks
dev/release/02-source.sh <version> <rc-number>

# Submit binary tasks using crossbow, the command will output the crossbow build id
dev/release/03-binary-submit.sh <version> <rc-number>

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

# Download the produced binaries
# This will download packages to a directory called packages/release-<version>-rc<rc-number>
dev/release/04-binary-download.sh <version> <rc-number>

# Sign and upload the binaries
#
# On macOS the only way I could get this to work was running "echo "UPDATESTARTUPTTY" | gpg-connect-agent" before running this comment
# otherwise I got errors referencing "ioctl" errors.
dev/release/05-binary-upload.sh <version> <rc-number>

# Sign and upload the Java artifacts
#
# Note that you need to press the "Close" button manually by Web interfacec
# after you complete the script:
#   https://repository.apache.org/#stagingRepositories
dev/release/06-java-upload.sh <version> <rc-number>

# Start verifications for binaries and wheels
dev/release/07-binary-verify.sh <version> <rc-number>

Verify the Release

# Once the automatic verification has passed merge the Release Candidate's branch to the maintenance branch
git checkout maint-<version>
git merge release-<version>-rc<rc-number>
git push apache maint-<version>

# Start the vote thread on dev@arrow.apache.org
# To regenerate the email template use
SOURCE_DEFAULT=0 SOURCE_VOTE=1 dev/release/02-source.sh <version> <rc-number>

Voting and approval

Start the vote thread on dev@arrow.apache.org and supply instructions for verifying the integrity of the release. Approval requires a net of 3 +1 votes from PMC members. A release cannot be vetoed.

Post-release tasks

After the release vote, we must undertake many tasks to update source artifacts, binary builds, and the Arrow website.

Be sure to go through on the following checklist:

  1. Make the released version as “RELEASED” on JIRA

  2. Make the CPP PARQUET related version as “RELEASED” on JIRA

  3. Start the new version on JIRA on the ARROW project

  4. Start the new version on JIRA for the related CPP PARQUET version

  5. Merge changes on release branch to maintenance branch for patch releases

  6. Add the new release to the Apache Reporter System

  7. Upload source

  8. Upload binaries

  9. Update website

  10. Update Homebrew packages

  11. Update MSYS2 package

  12. Upload RubyGems

  13. Upload JavaScript packages

  14. Upload C# packages

  15. Update conda recipes

  16. Upload wheels/sdist to pypi

  17. Publish Maven artifacts

  18. Update R packages

  19. Update vcpkg port

  20. Update Conan recipe

  21. Bump versions

  22. Update tags for Go modules

  23. Update docs

  24. Update version in Apache Arrow Cookbook

  25. Announce the new release

  26. Publish release blog posts

  27. Remove old artifacts

Mark the released version as “RELEASED” on JIRA
Start the new version on JIRA
Merge changes on release branch to maintenance branch for patch releases

Merge release-X.Y.Z-rcN to maint-X.Y.Z:

# git checkout maint-10.0.0
git checkout maint-X.Y.Z
# git merge release-10.0.0-rc0
git merge release-X.Y.Z-rcN
# git push -u apache maint-10.0.0
git push -u apache maint-X.Y.Z
Add the new release to the Apache Reporter System

Add relevant release data for Arrow to Apache reporter.

Upload source release artifacts to Subversion

A PMC member must commit the source release artifacts to Subversion:

# dev/release/post-01-upload.sh 0.1.0 0
dev/release/post-01-upload.sh <version> <rc>
Upload binary release artifacts to Artifactory

A committer must upload the binary release artifacts to Artifactory:

# dev/release/post-02-binary.sh 0.1.0 0
dev/release/post-02-binary.sh <version> <rc number>
Update website

Add a release note for the new version to our website and update the latest release information:

## Prepare your fork of https://github.com/apache/arrow-site .
## You need to do this only once.
# git clone git@github.com:kou/arrow-site.git ../
git clone git@github.com:<YOUR_GITHUB_ID>/arrow-site.git ../
cd ../arrow-site
## Add git@github.com:apache/arrow-site.git as "apache" remote.
git remote add apache git@github.com:apache/arrow-site.git
cd -

## Generate a release note for the new version, update the
## latest release information automatically.
# dev/release/post-03-website.sh 9.0.0 10.0.0
dev/release/post-03-website.sh OLD_X.OLD_Y.OLD_Z X.Y.Z

This script pushes a release-note-X.Y.Z branch to your apache/arrow-site fork. You need to open a pull request from the release-note-X.Y.Z branch on your Web browser.

Update Homebrew packages

Open a pull request to Homebrew:

## You need to run this on macOS or Linux that Homebrew is installed.

## Fork https://github.com/Homebrew/homebrew-core on GitHub.
## You need to do this only once.
##
## Prepare your fork of https://github.com/Homebrew/homebrew-core .
## You need to do this only once.
cd "$(brew --repository homebrew/core)"
# git remote add kou git@github.com:kou/homebrew-core.git
git remote add <YOUR_GITHUB_ID> git@github.com:<YOUR_GITHUB_ID>/homebrew-core.git
cd -

# dev/release/post-13-homebrew.sh 10.0.0 kou
dev/release/post-13-homebrew.sh X.Y.Z <YOUR_GITHUB_ID>

This script pushes a apache-arrow-X.Y.Z branch to your Homebrew/homebrew-core fork. You need to create a pull request from the apache-arrow-X.Y.Z branch with apache-arrow, apache-arrow-glib: X.Y.Z title on your Web browser.

Update MSYS2 packages

Open a pull request to MSYS2:

## Fork https://github.com/msys2/MINGW-packages on GitHub.
## You need to do this only once.
##
## Prepare your fork of https://github.com/msys2/MINGW-packages .
## You need to do this only once.
# git clone git@github.com:kou/MINGW-packages.git ../
git clone git@github.com:<YOUR_GITHUB_ID>/MINGW-packages.git ../
cd ../MINGW-packages
## Add https://github.com/msys2/MINGW-packages.git as "upstream" remote.
git remote add upstream https://github.com/msys2/MINGW-packages.git
cd -

# dev/release/post-12-msys2.sh 10.0.0 ../MINGW-packages
dev/release/post-12-msys2.sh X.Y.Z <YOUR_MINGW_PACAKGES_FORK>

This script pushes a arrow-X.Y.Z branch to your msys2/MINGW-packages fork. You need to create a pull request from the arrow-X.Y.Z branch with arrow: Update to X.Y.Z title on your Web browser.

Update RubyGems

You need an account on https://rubygems.org/ to release Ruby packages.

If you have an account on https://rubygems.org/ , you need to join owners of the following gems:

  • red-arrow gem

  • red-arrow-cuda gem

  • red-arrow-dataset gem

  • red-arrow-flight gem

  • red-arrow-flight-sql gem

  • red-gandiva gem

  • red-parquet gem

  • red-plasma gem

Existing owners can add a new account to the owners of them by the following command lines:

gem owner red-arrow -a NEW_ACCOUNT
gem owner red-arrow-cuda -a NEW_ACCOUNT
gem owner red-arrow-dataset -a NEW_ACCOUNT
gem owner red-arrow-flight -a NEW_ACCOUNT
gem owner red-arrow-flight-sql -a NEW_ACCOUNT
gem owner red-gandiva -a NEW_ACCOUNT
gem owner red-parquet -a NEW_ACCOUNT
gem owner red-plasma -a NEW_ACCOUNT

Update RubyGems after Homebrew packages and MSYS2 packages are updated:

# dev/release/post-04-ruby.sh 10.0.0
dev/release/post-04-ruby.sh X.Y.Z
Update JavaScript packages

In order to publish the binary build to npm, you will need to get access to the project by asking one of the current collaborators listed at https://www.npmjs.com/package/apache-arrow packages.

When you have access, you can publish releases to npm by running the npm-release.sh script inside the JavaScript source release:

# Login to npmjs.com (You need to do this only for the first time)
npm login --registry=https://registry.yarnpkg.com/

# dev/release/post-05-js.sh 10.0.0
dev/release/post-05-js.sh X.Y.Z
Update C# packages

You need an account on https://www.nuget.org/. You need to join owners of Apache.Arrow package. Existing owners can invite you to the owners at https://www.nuget.org/packages/Apache.Arrow/Manage .

You need to create an API key at https://www.nuget.org/account/apikeys to upload from command line.

Install the latest .NET Core SDK from https://dotnet.microsoft.com/download .

# NUGET_API_KEY=YOUR_NUGET_API_KEY dev/release/post-06-csharp.sh 10.0.0
NUGET_API_KEY=<your NuGet API key> dev/release/post-06-csharp.sh X.Y.Z
Upload wheels/sdist to PyPI

pip binary packages (called “wheels”) and source package (called “sdist”) are built using the crossbow tool that we used above during the release candidate creation process and then uploaded to PyPI (Python Package Index) under the pyarrow package.

We use the twine tool to upload wheels to PyPI:

# dev/release/post-09-python.sh 10.0.0
dev/release/post-09-python.sh <version>
Publish Maven packages
Update R packages
Update vcpkg port

Open a pull request to vcpkg:

## Fork https://github.com/microsoft/vcpkg on GitHub.
## You need to do this only once.
##
## Prepare your fork of https://github.com/microsoft/vcpkg .
## You need to do this only once.
# git clone git@github.com:kou/vcpkg.git ../
git clone git@github.com:<YOUR_GITHUB_ID>/vcpkg.git ../
cd ../vcpkg
./bootstrap-vcpkg.sh
## Add https://github.com/microsoft/vcpkg.git as "upstream" remote.
git remote add upstream https://github.com/microsoft/vcpkg.git
cd -

# dev/release/post-14-vcpkg.sh 10.0.0 ../vcpkg
dev/release/post-14-vcpkg.sh X.Y.Z <YOUR_VCPKG_FORK>

This script pushes a arrow-X.Y.Z branch to your microsoft/vcpkg fork. You need to create a pull request from the arrow-X.Y.Z branch with [arrow] Update to X.Y.Z title on your Web browser.

Update Conan port

TODO

Bump versions
# dev/release/post-11-bump-versions.sh 10.0.0 11.0.0
dev/release/post-11-bump-versions.sh X.Y.Z NEXT_X.NEXT_Y.NEXT_Z
Update tags for Go modules
# dev/release/post-10-go.sh 10.0.0
dev/release/post-10-go.sh X.Y.Z
Update docs

The documentations are generated in the release process. We just need to upload the generated documentations:

## Prepare your fork of https://github.com/apache/arrow-site .
## You need to do this only once.
# git clone git@github.com:kou/arrow-site.git ../
git clone git@github.com:<YOUR_GITHUB_ID>/arrow-site.git ../
cd ../arrow-site
## Add git@github.com:apache/arrow-site.git as "apache" remote.
git remote add apache git@github.com:apache/arrow-site.git
cd -

# dev/release/post-08-docs.sh 10.0.0 9.0.0
dev/release/post-08-docs.sh X.Y.Z PREVIOUS_X.PREVIOUS_Y.PREVIOUS_Z
Update version in Apache Arrow Cookbook

TODO

Announce the new release

Write a release announcement (see example) and send to announce@apache.org and dev@arrow.apache.org.

The announcement to announce@apache.org must be sent from your apache.org e-mail address to be accepted.

Publish release blog post

TODO

Remove old artifacts

Remove RC artifacts on https://dist.apache.org/repos/dist/dev/arrow/ and old release artifacts on https://dist.apache.org/repos/dist/release/arrow to follow the ASF policy:

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