From b4ea0a3842cd56246c019cca03c47975c857017a Mon Sep 17 00:00:00 2001
From: Sutou Kouhei <kou@clear-code.com>
Date: Wed, 23 Apr 2025 09:40:54 +0900
Subject: [PATCH] GH-587: [Release] Add .env description to
 dev/release/README.md

This also moves `GH_TOKEN` to `dev/release/.env`.
---
 dev/release/.env.example    |  5 ++
 dev/release/README.md       | 99 +++++++++++++++++++++++--------------
 dev/release/bump_version.sh |  7 +++
 dev/release/release.sh      |  7 +++
 dev/release/release_rc.sh   | 14 +++---
 5 files changed, 89 insertions(+), 43 deletions(-)

diff --git a/dev/release/.env.example b/dev/release/.env.example
index cc7fd58bfc..4a57e34ed3 100644
--- a/dev/release/.env.example
+++ b/dev/release/.env.example
@@ -15,6 +15,11 @@
 # specific language governing permissions and limitations
 # under the License.
 
+# The GitHub token to upload artifacts to GitHub Release.
+#
+# You must set this.
+#GH_TOKEN=secret
+
 # The GPG key ID to sign artifacts. The GPG key ID must be registered
 # to both of the followings:
 #
diff --git a/dev/release/README.md b/dev/release/README.md
index 9069a4fdaf..8aee0fd106 100644
--- a/dev/release/README.md
+++ b/dev/release/README.md
@@ -27,45 +27,38 @@
   4. Publish (detailed later)
   5. Bump version for new development (detailed later)
 
-### Bump version for new release
+### Prepare release environment
 
-Run `dev/release/bump_version.sh` on a working copy of your fork not
-`git@github.com:apache/arrow-java`:
+This step is needed only when you act as a release manager first time.
 
-```console
-$ git clone git@github.com:${YOUR_GITHUB_ACCOUNT}/arrow-java.git arrow-java.${YOUR_GITHUB_ACCOUNT}
-$ cd arrow-java.${YOUR_GITHUB_ACCOUNT}
-$ GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/bump_version.sh ${NEW_VERSION}
-```
+We use the following variables in multiple steps:
 
-Here is an example to bump version to 19.0.0:
+* `GH_TOKEN`: GitHub personal access token to automate GitHub related
+  operations
+* `GPG_KEY_ID`: PGP key ID that is used for signing official artifacts
+  by GnuPG
 
-```
-$ GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/bump_version.sh 19.0.0
-```
+We use `dev/release/.env` to share these variables in multiple
+steps. You can use `dev/release/.env.example` as a template:
 
-It creates a feature branch and adds a commit that bumps version. This
-opens a pull request from the feature branch by `gh pr create`. So you
-need `gh` command and GitHub personal access token.
+```console
+$ cp dev/release/.env{.example,}
+$ chmod go-r dev/release/.env
+$ editor dev/release/.env
+```
 
-See also:
+See
 https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
+how to prepare GitHub personal access token for `GH_TOKEN`.
 
-We need to merge the pull request before we cut a RC. If we try cut a
-RC without merging the pull request, the script to cut a RC is failed.
+Note that you also need to install `gh` command because our scripts
+use `gh` command to use GitHub API. See
+https://github.com/cli/cli#installation how to install `gh`
+command.
 
-### Prepare RC and vote
-
-You can use `dev/release/release_rc.sh`.
-
-Requirements to run `release_rc.sh`:
-
-  * You must be an Apache Arrow committer or PMC member
-  * You must prepare your PGP key for signing
-  * You must configure Maven
-
-If you don't have a PGP key,
-https://infra.apache.org/release-signing.html#generate may be helpful.
+If you don't have a PGP key for `GPG_KEY_ID`, see
+https://infra.apache.org/release-signing.html#genegrate how to
+generate your PGP key.
 
 Your PGP key must be registered to the followings:
 
@@ -85,6 +78,40 @@ $ head KEYS
 $ svn ci KEYS
 ```
 
+### Bump version for new release
+
+Run `dev/release/bump_version.sh` on a working copy of your fork not
+`git@github.com:apache/arrow-java`:
+
+```console
+$ git clone git@github.com:${YOUR_GITHUB_ACCOUNT}/arrow-java.git arrow-java.${YOUR_GITHUB_ACCOUNT}
+$ cd arrow-java.${YOUR_GITHUB_ACCOUNT}
+$ dev/release/bump_version.sh ${NEW_VERSION}
+```
+
+Here is an example to bump version to 19.0.0:
+
+```
+$ dev/release/bump_version.sh 19.0.0
+```
+
+It creates a feature branch and adds a commit that bumps version. This
+opens a pull request from the feature branch.
+
+We need to merge the pull request before we cut a RC. If we try
+cutting a RC without merging the pull request, the script to cut a RC
+is failed.
+
+### Prepare RC and vote
+
+You can use `dev/release/release_rc.sh`.
+
+Requirements to run `release_rc.sh`:
+
+  * You must be an Apache Arrow committer or PMC member
+  * You must prepare your PGP key for signing
+  * You must configure Maven
+
 Configure Maven to publish artifacts to Apache repositories. You will
 need to setup a master password at `~/.m2/settings-security.xml` and
 `~/.m2/settings.xml` as specified on [the Apache
@@ -102,7 +129,7 @@ Run `dev/release/release_rc.sh` on a working copy of
 ```console
 $ git clone git@github.com:apache/arrow-java.git
 $ cd arrow-java
-$ GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/release_rc.sh ${RC}
+$ dev/release/release_rc.sh ${RC}
 (Send a vote email to dev@arrow.apache.org.
  You can use a draft shown by release_rc.sh for the email.)
 ```
@@ -110,7 +137,7 @@ $ GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/release_rc.sh ${RC}
 Here is an example to release RC1:
 
 ```console
-$ GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/release_rc.sh 1
+$ dev/release/release_rc.sh 1
 ```
 
 The argument of `release_rc.sh` is the RC number. If RC1 has a
@@ -128,13 +155,13 @@ Run `dev/release/release.sh` on a working copy of
 archive to apache.org:
 
 ```console
-$ GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/release.sh ${VERSION} ${RC}
+$ dev/release/release.sh ${VERSION} ${RC}
 ```
 
 Here is an example to release 19.0.0 RC1:
 
 ```console
-$ GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/release.sh 19.0.0 1
+$ dev/release/release.sh 19.0.0 1
 ```
 
 Add the release to ASF's report database via [Apache Committee Report
@@ -160,13 +187,13 @@ Run `dev/release/bump_version.sh` on a working copy of your fork not
 ```console
 $ git clone git@github.com:${YOUR_GITHUB_ACCOUNT}/arrow-java.git arrow-java.${YOUR_GITHUB_ACCOUNT}
 $ cd arrow-java.${YOUR_GITHUB_ACCOUNT}
-$ GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/bump_version.sh ${NEW_VERSION}-SNAPSHOT
+$ dev/release/bump_version.sh ${NEW_VERSION}-SNAPSHOT
 ```
 
 Here is an example to bump version to 19.0.1-SNAPSHOT:
 
 ```
-$ GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/bump_version.sh 19.0.0-SNAPSHOT
+$ dev/release/bump_version.sh 19.0.0-SNAPSHOT
 ```
 
 It creates a feature branch and adds a commit that bumps version. This
diff --git a/dev/release/bump_version.sh b/dev/release/bump_version.sh
index d1c127de35..458e930f98 100755
--- a/dev/release/bump_version.sh
+++ b/dev/release/bump_version.sh
@@ -31,6 +31,13 @@ fi
 
 version=$1
 
+if [ ! -f "${SOURCE_DIR}/.env" ]; then
+  echo "You must create ${SOURCE_DIR}/.env"
+  echo "You can use ${SOURCE_DIR}/.env.example as template"
+  exit 1
+fi
+. "${SOURCE_DIR}/.env"
+
 cd "${SOURCE_TOP_DIR}"
 
 git_origin_url="$(git remote get-url origin)"
diff --git a/dev/release/release.sh b/dev/release/release.sh
index c5e67907e2..70e1f96454 100755
--- a/dev/release/release.sh
+++ b/dev/release/release.sh
@@ -28,6 +28,13 @@ fi
 version=$1
 rc=$2
 
+if [ ! -f "${SOURCE_DIR}/.env" ]; then
+  echo "You must create ${SOURCE_DIR}/.env"
+  echo "You can use ${SOURCE_DIR}/.env.example as template"
+  exit 1
+fi
+. "${SOURCE_DIR}/.env"
+
 git_origin_url="$(git remote get-url origin)"
 repository="${git_origin_url#*github.com?}"
 repository="${repository%.git}"
diff --git a/dev/release/release_rc.sh b/dev/release/release_rc.sh
index b0107dce85..ff77718b8d 100755
--- a/dev/release/release_rc.sh
+++ b/dev/release/release_rc.sh
@@ -36,6 +36,13 @@ rc=$1
 : "${RELEASE_SIGN:=${RELEASE_DEFAULT}}"
 : "${RELEASE_UPLOAD:=${RELEASE_DEFAULT}}"
 
+if [ ! -f "${SOURCE_DIR}/.env" ]; then
+  echo "You must create ${SOURCE_DIR}/.env"
+  echo "You can use ${SOURCE_DIR}/.env.example as template"
+  exit 1
+fi
+. "${SOURCE_DIR}/.env"
+
 cd "${SOURCE_TOP_DIR}"
 
 if [ "${RELEASE_PULL}" -gt 0 ] || [ "${RELEASE_PUSH_TAG}" -gt 0 ]; then
@@ -84,13 +91,6 @@ artifacts_dir="apache-arrow-java-${version}-rc${rc}"
 signed_artifacts_dir="${artifacts_dir}-signed"
 
 if [ "${RELEASE_SIGN}" -gt 0 ]; then
-  if [ ! -f "${SOURCE_DIR}/.env" ]; then
-    echo "You must create ${SOURCE_DIR}/.env"
-    echo "You can use ${SOURCE_DIR}/.env.example as template"
-    exit 1
-  fi
-  . "${SOURCE_DIR}/.env"
-
   git_origin_url="$(git remote get-url origin)"
   repository="${git_origin_url#*github.com?}"
   repository="${repository%.git}"