This is an automated email from the ASF dual-hosted git repository.
brycemecum pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new 438cf9bd2d GH-45140: [Dev][Release] Release guide improvements (#45141)
438cf9bd2d is described below
commit 438cf9bd2d31506635bc56ca0371df53030ff4d1
Author: Bryce Mecum <[email protected]>
AuthorDate: Tue Jan 7 11:18:47 2025 -0800
GH-45140: [Dev][Release] Release guide improvements (#45141)
### 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]>
---
docs/source/developers/release.rst | 127 +++++++++++++++++++++++--------------
1 file changed, 80 insertions(+), 47 deletions(-)
diff --git a/docs/source/developers/release.rst
b/docs/source/developers/release.rst
index 52f4a751dc..605a1adbe1 100644
--- a/docs/source/developers/release.rst
+++ b/docs/source/developers/release.rst
@@ -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
==========
@@ -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
@@ -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::
@@ -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
@@ -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
@@ -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
-----------------------------------------------------------------------
@@ -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>
@@ -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>
@@ -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
@@ -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
@@ -266,7 +296,6 @@ 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
@@ -274,28 +303,6 @@ Be sure to go through on the following checklist:
#. 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
@@ -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
@@ -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.
@@ -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
@@ -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
@@ -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
@@ -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.
