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

Author: amoeba

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,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
@@ -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.