diff --git a/docs/source/developers/release.rst b/docs/source/developers/release.rst index 52f4a751dcc81..605a1adbe10d7 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 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) # - # starts at 0 and increments every time the Release Candidate is burned + # 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 # Push the release candidate tag - git push -u apache apache-arrow-rc + git push -u apache apache-arrow--rc # Push the release candidate branch in order to trigger verification jobs later git push -u apache release--rc @@ -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 @@ -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 # 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 # 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 + # dev/release/post-16-conan.sh 10.0.1 ../conan-center-index + dev/release/post-16-conan.sh X.Y.Z 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 `_ + 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 `_ handle. + Post about the release and link to the blog post on social media. The project + has two official accounts: + + * Twitter/X: `@ApacheArrow `_ + * LinkedIn: https://www.linkedin.com/company/apache-arrow/ - PMC members have access or can request access, after which they can post via `TweetDeck `_. + 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.