Skip to content

Commit

Permalink
GH-45140: [Dev][Release] Release guide improvements (#45141)
Browse files Browse the repository at this point in the history 
### What changes are included in this PR?

Updates to the release guide. Mostly changes to make the guide up to date with how release are being done currently.

### Are these changes tested?

Previewed locally.

### Are there any user-facing changes?

More accurate docs.

Fixes #45140 
* GitHub Issue: #45140

Lead-authored-by: Bryce Mecum <[email protected]>
Co-authored-by: Sutou Kouhei <[email protected]>
Signed-off-by: Bryce Mecum <[email protected]>
  • Loading branch information
@amoeba @kou
amoeba and kou authored Jan 7, 2025
1 parent 2c5ae51 commit 438cf9b
Showing 1 changed file with 80 additions and 47 deletions.
127 changes: 80 additions & 47 deletions docs/source/developers/release.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,10 @@ 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.
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
==========
Expand All @@ -36,8 +39,15 @@ 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.
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.

.. dropdown:: Requirements
:animate: fade-in-slide-down
Expand Down Expand Up @@ -67,7 +77,8 @@ generated properly.
Before creating a Release Candidate
===================================

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

.. code-block::
Expand All @@ -78,7 +89,8 @@ Ensure local tags are removed, gpg-agent is set and JIRA tickets are correctly a
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.
# 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
Expand Down Expand Up @@ -149,7 +161,7 @@ Create or update the corresponding maintenance 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
archery release cherry-pick X.Y.Z --execute
# Push the maintenance branch to the remote repository
git push -u apache maint-X.Y.Z
Expand All @@ -158,14 +170,30 @@ Create or update the corresponding maintenance branch
.. code-block::
# 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
# 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 --jira-cache /tmp/jiracache cherry-pick X.Y.Z --continue --execute
archery release cherry-pick X.Y.Z --continue --execute
# Push the updated maintenance branch to the remote repository
git push -u apache maint-X.Y.Z
Optional: Test Before Creating a Release Candidate
--------------------------------------------------

Some release managers prefer to perform testing before creating the first
release candidate to avoid the need to create multiple release candidates within
a given release.

To test before creating a release candiate:

* Create a pull request from the up-to-date maint-X.Y.Z branch onto main
* Title the pull request "WIP: Dummy PR to check maint-X.Y.Z status"
* Comment on the pull request to trigger the relevant Crossbow jobs:

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

Create the Release Candidate branch from the updated maintenance branch
-----------------------------------------------------------------------

Expand All @@ -178,12 +206,12 @@ Create the Release Candidate branch from the updated maintenance branch
# 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
# <rc-number> starts at 0 and increments every time the Release Candidate is created
# 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 candidate tag
git push -u apache apache-arrow-<version>rc<rc-number>
git push -u apache apache-arrow-<version>-rc<rc-number>
# Push the release candidate branch in order to trigger verification jobs later
git push -u apache release-<version>-rc<rc-number>
Expand All @@ -194,6 +222,7 @@ Build source and binaries and submit them
# Build the source release tarball and create Pull Request with verification tasks
#
# NOTE: This must be run by a PMC member
# NOTE: You need to have GitHub CLI installed to run this script.
dev/release/02-source.sh <version> <rc-number>
Expand All @@ -209,13 +238,16 @@ Build source and binaries and submit them
# Sign and upload the binaries
#
# NOTE: This must be run by a PMC member
#
# 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 MATLAB artifacts to the GitHub Releases area.
#
# Note that you need to have GitHub CLI installed to run this script.
# NOTE: This must be run by a PMC member
# NOTE: You need to have GitHub CLI installed to run this script.
dev/release/06-matlab-upload.sh <version> <rc-number>
# Start verifications for binaries and wheels
Expand Down Expand Up @@ -246,8 +278,6 @@ After the release vote, we must undertake many tasks to update source artifacts,
Be sure to go through on the following checklist:

#. Update the released milestone Date and set to "Closed" on GitHub
#. Make the CPP PARQUET related version as "RELEASED" on JIRA
#. Start the new version on JIRA for the related CPP PARQUET version
#. Merge changes on release branch to maintenance branch for patch releases
#. Add the new release to the Apache Reporter System
#. Push release tag
Expand All @@ -266,36 +296,13 @@ Be sure to go through on the following checklist:
#. Update vcpkg port
#. Update Conan recipe
#. Bump versions
#. Update tags for Go modules
#. Update docs
#. Update version in Apache Arrow Cookbook
#. Announce the new release
#. Publish release blog posts
#. Announce the release on Twitter
#. Remove old artifacts

.. dropdown:: Mark the released version as "RELEASED" on JIRA
:animate: fade-in-slide-down
:class-title: sd-fs-5
:class-container: sd-shadow-md

- Open https://issues.apache.org/jira/plugins/servlet/project-config/ARROW/administer-versions
- Click "..." for the release version in "Actions" column
- Select "Release"
- Set "Release date"
- Click "Release" button

.. dropdown:: Start the new version on JIRA
:animate: fade-in-slide-down
:class-title: sd-fs-5
:class-container: sd-shadow-md

- Open https://issues.apache.org/jira/plugins/servlet/project-config/ARROW/administer-versions
- Click "..." for the next version in "Actions" column
- Select "Edit"
- Set "Start date"
- Click "Save" button

.. dropdown:: Merge changes on release branch to maintenance branch for patch releases
:animate: fade-in-slide-down
:class-title: sd-fs-5
Expand Down Expand Up @@ -588,7 +595,7 @@ Be sure to go through on the following checklist:
:class-title: sd-fs-5
:class-container: sd-shadow-md

Open a pull request to vcpkg:
Open a pull request to Conan:

.. code-block:: Bash
Expand All @@ -604,8 +611,8 @@ Be sure to go through on the following checklist:
git remote add upstream https://github.com/conan-io/conan-center-index.git
cd -
# dev/release/post-17-conan.sh 10.0.1 ../conan-center-index
dev/release/post-17-conan.sh X.Y.Z <YOUR_CONAN_CENTER_INDEX_FORK>
# dev/release/post-16-conan.sh 10.0.1 ../conan-center-index
dev/release/post-16-conan.sh X.Y.Z <YOUR_CONAN_CENTER_INDEX_FORK>
This script pushes a ``arrow-X.Y.Z`` branch to your ``conan-io/conan-center-index`` fork. You need to create a pull request from the ``arrow-X.Y.Z`` branch on your Web browser.

Expand All @@ -627,7 +634,8 @@ Be sure to go through on the following checklist:
:class-title: sd-fs-5
:class-container: sd-shadow-md

The documentations are generated in the release process. We just need to upload the generated documentations:
Documentation is generated as part of the release process. We just need to
upload the generated documentation:

.. code-block:: Bash
Expand All @@ -650,7 +658,8 @@ Be sure to go through on the following checklist:
:class-title: sd-fs-5
:class-container: sd-shadow-md

TODO
Follow `the documentation <https://github.com/apache/arrow-cookbook/tree/main/dev/release>`_
in the Apache Arrow Cookbook repository

.. dropdown:: Announce the new release
:animate: fade-in-slide-down
Expand All @@ -666,16 +675,38 @@ Be sure to go through on the following checklist:
:class-title: sd-fs-5
:class-container: sd-shadow-md

TODO
The blog post process isn't automated. The rough set of steps we usually take
are:

.. dropdown:: Announce the release on Twitter
* Clone https://github.com/apache/arrow-site.
* Create a new branch off ``main`` for the blog post pull request we're
creating.
* Duplicate a recent blog post entry in the ``_posts`` subfolder and update
the filename and YAML metadata.

* Set the date in the filename and in the YAML metadata to the date that the
release candidate vote thread for the release closed (in GMT).

* *For minor releases only*, remove any section about community updates (new
committers, PMC members, etc).
* Update the remainder of the text as needed
* Create the pull request
* In the pull request, ping contributors in each section requesting help
filling in the details for each section.


.. dropdown:: Announce the release on social media
:animate: fade-in-slide-down
:class-title: sd-fs-5
:class-container: sd-shadow-md

Post the release blog post on Twitter from the `@ApacheArrow <https://twitter.com/ApacheArrow>`_ handle.
Post about the release and link to the blog post on social media. The project
has two official accounts:

* Twitter/X: `@ApacheArrow <https://twitter.com/ApacheArrow>`_
* LinkedIn: https://www.linkedin.com/company/apache-arrow/

PMC members have access or can request access, after which they can post via `TweetDeck <https://tweetdeck.twitter.com>`_.
PMC members have access or can request access to post under these accounts.

.. dropdown:: Remove old artifacts
:animate: fade-in-slide-down
Expand All @@ -687,3 +718,5 @@ Be sure to go through on the following checklist:
.. code-block:: Bash
dev/release/post-09-remove-old-artifacts.sh
Note: This step must be done by a PMC member.

0 comments on commit 438cf9b

Please sign in to comment.