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. The person acting as Release Manager must at least have committer status in order to perform the tasks below. If the Release Manager is a committer but not a member of the PMC, some tasks will need to be delegated to a PMC member and these are marked below accordingly.
Principles#
The Apache Arrow Release follows the guidelines defined at the Apache Software Foundation Release Policy.
Preparing for the release#
In advance to the Release date the Release Manager communicates with the community usually via Zulip, Mailing List or the bi-weekly community call about the upcoming release and proposes a feature freeze date.
The feature freeze date is the date the maintenance branch is created and from that point no new features are allowed to be added to the release, unless there is community consensus to allow it, and only bug fixes will be accepted.
Once the feature freeze is in place issues labelled as blocker must be resolved before
the first release candidate can be created.
Before creating a release candidate, the Release Manager must ensure that any resolved GitHub issues have the appropriate milestone set so that the changelog is generated properly.
Note that pull requests without a corresponding GitHub issue won’t be detected by the cherry-pick script and must be cherry-picked manually by the release manager onto the maintenance branch. Examples include MINOR and Dependabot pull requests. For this reason, it’s encouraged to avoid the need for manual cherry-picking by creating issues for any pull requests that are merged to the default branch after the release maintenance branch has been created.
Before creating a Release Candidate#
Ensure local tags are removed, gpg-agent is set and GitHub issues are correctly assigned.
# Delete the local tag for RC1 or later
git tag -d apache-arrow-<version>
# Setup gpg agent for signing binary artifacts
source dev/release/setup-gpg-agent.sh
# Curate the release
# The end of the generated report shows any GitHub issues with the wrong
# version number assigned.
archery release curate <version>
Ensure a major version milestone for a follow up release is created on GitHub. This will automatically be used by our merge script as the new version for issues closed when the maintenance branch is created.
Patch Releases#
We usually create patch releases once a major breaking issue has been identified. Issues that are identified as major breaking issues can be security fixes, broken packages for specific builds and others.
Any developer can ask for a patch release to be generated sending an email to the Arrow development mailing-list with the reason of why a new release is necessary. If there is consensus and there is a Release Manager willing to make the effort to create the release a patch release can be created.
Committers can tag issues that should be included on the next patch release using the
backport-candidate label. Is the responsibility of the author or the committer to add the
label to the issue to help the Release Manager identify the issues that should be backported.
If a specific issue is identified as the reason to create a patch release the Release Manager should validate that, at least, this issue is correctly tagged and included in the patch release.
Be sure to go through on the following checklist:
Create milestone
Create maintenance branch
Include issue that was requested as requiring new patch release
Add new milestone to issues with
backport-candidatelabelcherry-pick issues into maintenance branch
Creating a Release Candidate#
These are the different steps that are required to create a Release Candidate.
For the initial Release Candidate on a major release, we will create a maintenance branch from main. This is done on the feature freeze date.
Follow up Release Candidates will update the maintenance branch by cherry-picking specific commits.
For the initial Release Candidate for a minor or a patch release we will create
a maintenance branch from the previous corresponding release tag. For example,
for a 25.0.1 patch we will create the maintenance branch from the
apache-arrow-25.0.0. This is automatically done by archery release cherry-pick.
The maintenance branch is named after the release series, not after the exact version being
released, for example for patch release (25.0.1) the maintenance branch will be
maint-25.0.x.
If further patch releases are prepared, i.e., 25.0.2 it will be created on the same
maint-25.0.x branch.
Create or update the corresponding maintenance branch#
# Execute the following from an up to date main branch.
# This will create the maintenance branch locally.
# X.Y.Z corresponds with the Major, Minor and Patch version number
# of the release respectively. As an example 9.0.0
archery release cherry-pick X.Y.Z --execute
# Push the maintenance branch to the remote repository
git push -u upstream <maintenance-branch>
# 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
# milestone on GitHub is set to the following release.
archery release cherry-pick X.Y.Z --continue
# Update the maintenance branch with the previous commits
archery release