Sparkリリースの準備

背景

Sparkのリリースマネージャーの役割は、いくつかの異なる責任を負うことを意味します

1. セットアップの準備
2. リリース候補の準備
   1. リリースブランチの作成
   2. コミュニティへのタイミングの通知
   3. コンポーネントリーダーと協力してJIRAをクリーンアップする
   4. 必要なバージョン更新を含む、そのブランチでのコード変更
3. リリースのための投票プロセスの実行
   1. 自動ツールを使用してリリース候補を作成する
   2. 投票の呼びかけと問題のトリアージ
4. リリースの確定と投稿
   1. Sparkウェブサイトの更新
   2. リリースノートの作成
   3. リリースの発表

セットアップの準備

初めてリリースマネージャーを務める場合は、以下の内容からプロセスについて学ぶことができます

• リリース署名 https://apache.dokyumento.jp/dev/release-signing.html
• 署名のためのgpg https://apache.dokyumento.jp/dev/openpgp.html
• svn https://infra.apache.org/version-control.html#svn

gpgキーの準備

既にキーをアップロードしている場合は、このセクションをスキップできます。

キーの生成

gpg 2.0.12 の例を以下に示します。gpg バージョン 1 シリーズを使用する場合は、詳細について generate-key を参照してください。

$ gpg --full-gen-key
gpg (GnuPG) 2.0.12; Copyright (C) 2009 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 
Key does not expire at all
Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: Robert Burrell Donkin
Email address: rdonkin@apache.org
Comment: CODE SIGNING KEY
You selected this USER-ID:
    "Robert Burrell Donkin (CODE SIGNING KEY) <rdonkin@apache.org>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: key 04B3B5C426A27D33 marked as ultimately trusted
gpg: revocation certificate stored as '/home/ubuntu/.gnupg/openpgp-revocs.d/08071B1E23C8A7E2CA1E891A04B3B5C426A27D33.rev'
public and secret key created and signed.

pub   rsa4096 2021-08-19 [SC]
      08071B1E23C8A7E2CA1E891A04B3B5C426A27D33
uid                      Jack (test) <Jack@mail.com>
sub   rsa4096 2021-08-19 [E]

公開鍵の最後の8桁（26A27D33）は、キーIDです。

キーのアップロード

公開鍵を生成した後、公開鍵サーバーにアップロードする必要があります

$ gpg --keyserver hkps://keys.openpgp.org --send-key 26A27D33

詳細は、keyserver-upload を参照してください。

コード署名キーでKEYSファイルを更新する

コード署名キー（別名ASCII装甲公開鍵）を取得するには、次のコマンドを実行します

$ gpg --export --armor 26A27D33

そして、生成されたキーをKEYSファイルに以下のコマンドで追加します

# Move dev/ to release/ when the voting is completed. See Finalize the Release below
svn co --depth=files "https://dist.apache.org/repos/dist/dev/spark" svn-spark
# edit svn-spark/KEYS file
svn ci --username $ASF_USERNAME --password "$ASF_PASSWORD" -m"Update KEYS"

別のマシンでリリースを実行する場合は、`gpg --export-secret-keys` コマンドと `gpg --import` コマンドを使用して、秘密鍵をそのマシンに転送できます。

Dockerのインストール

リリース候補を作成するためのスクリプトは、docker を介して実行されます。 これらのスクリプトを実行する前に、docker をインストールする必要があります。 root以外のユーザーとしてdockerを実行できることを確認してください。 詳細については、https://docs.docker.com/install/linux/linux-postinstall を参照してください。

リリースのためのSparkの準備

リリースを準備するための主な手順は、リリースブランチを作成することです。 これは標準のGitブランチメカニズムを介して行われ、ブランチが作成されたらコミュニティに発表する必要があります。

リリース候補の作成

これが最初のRCでない場合は、前回のRC以降に解決されたJIRAの問題が `Resolved` とマークされ、`Target Versions` がこのリリースバージョンに設定されていることを確認してください。

このリリースを対象とする保留中のPRに関する問題を追跡するには、JIRAで `project = SPARK AND "Target Version/s" = "12340470" AND status in (Open, Reopened, "In Progress")` のようなクエリを使用してフィルターを作成します

使用するターゲットバージョン文字列値については、そのターゲットバージョンを持つ既存の問題を調べてバージョンをクリックすることにより、リリースに対応する数値を見つけます（例：2.2.1をターゲットとする問題を見つけて、そのターゲットバージョンフィールドのバージョンリンクをクリックします）

`git log` から、それらが実際に新しいRCに含まれているかどうかを確認します。 `release-notes` ラベルが付いたJIRAの問題を確認し、重大な変更については関連する移行ガイドに、またはWebサイトのリリースニュースに後で文書化されていることを確認します。

リリース候補を作成するには、4つの手順があります

1. リリース候補のgitタグを作成します。
2. リリーバイナリとソースをパッケージ化し、ApacheステージングSVNリポジトリにアップロードします。
3. リリースドキュメントを作成し、ApacheステージングSVNリポジトリにアップロードします。
4. スナップショットをApacheステージングMavenリポジトリに公開します。

リリース候補を作成するプロセスは、`dev/create-release/do-release-docker.sh` スクリプトによって自動化されています。 このスクリプトを実行し、必要な情報を入力して、完了するまで待ちます。 `-s` オプションを使用して、単一の手順を実行することもできます。 `do-release-docker.sh -h` を実行して、詳細を確認してください。

リリース候補の投票を呼びかける

リリース投票は、Apache Spark開発者リスト（PMCが投票）で行われます。 これがどのように進むかを確認するには、過去の投票スレッドをご覧ください。 メールは この形式 に従う必要があります。

• https://s.apache.org/ を使用して、JIRAの完全なリストへの短縮リンクを作成します
• 可能であれば、リリースノートのドラフトをメールに添付してください
• 投票の終了時刻がUTC形式であることを確認してください。 生成するには、このスクリプトを使用します
• メールがテキスト形式であり、リンクが正しいことを確認してください

投票が終わったら、合計を記した要約メールを `[VOTE][RESULT] ...` のような件名で送信する必要があります。

リリースを確定する

`dev/create-release/do-release-docker.sh` スクリプト（`finalize` ステップ）は、以下の手順のほとんどを自動化しますが、**以下は除きます**

• CRANへの公開
• Algolia Crawlerの構成の更新
• ミラーネットワークから古いリリースを削除する
• Sparkウェブサイトの残りの部分を更新する
• Spark Dockerイメージの作成とアップロード
• アナウンスを作成する

各手順の後、結果を手動で確認してください。

Apacheリリースディレクトリにアップロードする

注意してください！

この手順は元に戻せないため、正しいステージングリポジトリを選択したことを確認してください。 アーティファクトをリリースフォルダーに移動すると、削除できなくなります。

投票が可決された後、バイナリをApacheミラーにアップロードするには、バイナリをdevディレクトリ（投票された場所）からリリースディレクトリに移動します。 この「移動」は、実際のリリースディレクトリに物を追加できる唯一の方法です。 （注：PMCのみがリリースディレクトリに移動できます）

# Move the sub-directory in "dev" to the
# corresponding directory in "release"
$ export SVN_EDITOR=vim
$ svn mv https://dist.apache.org/repos/dist/dev/spark/v1.1.1-rc2-bin https://dist.apache.org/repos/dist/release/spark/spark-1.1.1

# If you've added your signing key to the KEYS file, also update the release copy.
svn co --depth=files "https://dist.apache.org/repos/dist/release/spark" svn-spark
curl "https://dist.apache.org/repos/dist/dev/spark/KEYS" > svn-spark/KEYS
(cd svn-spark && svn ci --username $ASF_USERNAME --password "$ASF_PASSWORD" -m"Update KEYS")

https://apache.dokyumento.jp/dist/spark/ にリソースが存在することを確認します。 表示されるまでしばらく時間がかかる場合があります。 これはApacheネットワーク全体にミラーリングされます。 https://checker.apache.org/projs/spark.html でリリースのリリースチェッカーの結果を確認してください。

Maven Central Repositoryの場合、Apache Nexus Repository Managerからリリースできます。 これは既に `release-build.sh publish-release` ステップによって設定されています。 ログインし、ステージングリポジトリを開き、投票されたリポジトリ（例：https://repository.apache.org/content/repositories/orgapachespark-1257/ のorgapachespark-1257）を見つけ、選択して[リリース]をクリックし、確認します。 成功した場合、https://repository.apache.org/content/repositories/releases/org/apache/spark/spark-core_2.11/2.2.1/ の下に、https://repository.apache.org/content/groups/maven-staging-group/org/apache/spark/spark-core_2.11/2.2.1/ の下にも同じものが表示されます（正しいリリースバージョンを探してください）。 しばらくすると、これは自動的にMaven Centralに同期されます。

PyPIにアップロードする

`spark-upload` アカウントの資格情報が必要です。これは、このメッセージ と このメッセージ （PMCメンバーのみ表示可能）にあります。

アーティファクトは、twineを使用してアップロードできます。 次のコマンドを実行するだけです

twine upload --repository-url https://upload.pypi.org/legacy/ pyspark-{version}.tar.gz pyspark-{version}.tar.gz.asc

新しいリリースに一致するファイルのコマンドを調整します。 何らかの理由でtwineのアップロードが正しくない場合（例：httpエラーまたはその他の問題）、アーティファクトの名前を `pyspark-version.post0.tar.gz` に変更し、PyPIから古いアーティファクトを削除して、再アップロードできます。

CRANへの公開

CRANへの公開は、このフォームを使用して行われます。 さらに手動の手順が必要になるため、PMCにも連絡してください。

リポジトリからRCアーティファクトを削除する

注意！承認されたRCのドキュメントのバックアップを作成しなかった場合、これはバックアップを作成できる最後の機会です。 これは、次の手順でドキュメントをWebサイトにアップロードするために使用されます。 ディレクトリを削除する前に、svnからドキュメントをチェックアウトしてください。

投票が可決され、承認されたRCをリリーsiriポジトリに移動した後、ステージングリポジトリからRCディレクトリを削除する必要があります。 例えば

svn rm https://dist.apache.org/repos/dist/dev/spark/v2.3.1-rc1-bin/ \
  https://dist.apache.org/repos/dist/dev/spark/v2.3.1-rc1-docs/ \
  -m"Removing RC artifacts."

Apache Nexus Repository Managerから公開されていないステージングリポジトリも必ず削除してください。

ミラーネットワークから古いリリースを削除する

Sparkは、ミラーネットワーク内の各ブランチの最新のメンテナンスリリースを常に保持しています。 古いバージョンを削除するには、svn rmを使用します

$ svn rm https://dist.apache.org/repos/dist/release/spark/spark-1.1.0

また、サイトで正しいリンクが生成されるように、リリースがミラーリングされなくなったことを示すために `js/download.js` を更新する必要があります。

Spark Apache™リポジトリを更新する

合格したリリース候補のタグ付きコミットをチェックアウトし、正しいバージョ

$ git tag v1.1.1 v1.1.1-rc2 # the RC that passed
$ git push apache v1.1.1

Algolia Crawlerの構成の更新

Sparkドキュメントウェブサイトの検索ボックスは、Algolia Crawlerを利用しています。リリース前に、Algolia Crawler管理コンソールで、Apache Sparkのクローラー設定を新しいバージョンに更新してください。設定へのアクセス権がない場合は、Gengliang WangまたはXiao Liに連絡して支援を求めてください。

Sparkウェブサイトを更新する

生成されたドキュメントをアップロードする

ウェブサイトのリポジトリはhttps://github.com/apache/spark-websiteにあります。

最新のRCの生成済みドキュメントを削除しないことをお勧めします。そうすることで、spark-websiteに直接コピーできます。削除した場合は、ドキュメントを再構築する必要があります。

# Build the latest docs
$ git checkout v1.1.1
$ cd docs
$ PRODUCTION=1 bundle exec jekyll build

# Copy the new documentation to Apache
$ git clone https://github.com/apache/spark-website
...
$ cp -R _site spark-website/site/docs/1.1.1

# Update the "latest" link
$ cd spark-website/site/docs
$ rm latest
$ ln -s 1.1.1 latest

Sparkウェブサイトの残りの部分を更新する

次に、Sparkウェブサイトの残りの部分を更新します。以前のリリースがどのように文書化されているかを確認してください（すべてのHTMLファイルの変更はjekyllによって生成されます）。特に

• 新しいリリースが最新リリースの場合は、_layouts/global.htmlを更新します
• 新しいリリースのドキュメントへのリンクを追加するために、documentation.mdを更新します
• 新しいリリースをjs/downloads.jsに追加します（リリースの順序に注意してください）
• 更新が必要なものがないか、security.mdを確認します

$ git add 1.1.1
$ git commit -m "Add docs for Spark 1.1.1"

次に、リリースノートを作成します。JIRAのリリースページに移動し、リストからリリースバージョンを選択し、「リリースノート」をクリックします。このURLをコピーし、s.apache.orgで短縮URLを作成します。Apacheアカウントにサインインし、IDをspark-2.1.2のように選択します。この短縮URLを含めるために、releases/_postsの下に新しいリリース投稿を作成します。投稿の日付は、作成した日付にする必要があります。

次に、bundle exec jekyll buildを実行して、siteディレクトリを更新します。

プルリクエストが大きくなることを考慮して、コード変更と生成されたsiteディレクトリのコミットを分けて、レビューを容易にしてください。

変更をasf-siteブランチにマージした後、ASFのgitとウェブサイト、およびGitHubミラー間の同期を強制するために、フォローアップの空のコミットを作成する必要がある場合があります。何らかの理由で、このリポジトリの同期は信頼できないようです。

関連事項として、JIRAでバージョンがリリース済みとしてマークされていることを確認してください。上記のリリースページ（例：https://issues.apache.org/jira/projects/SPARK/versions/12340295）を見つけ、右側の「リリース」ボタンをクリックして、リリース日を入力します。

（一般的に、これはメジャーおよびマイナーリリースの場合のみで、パッチリリースには該当しません）コントリビューターリストは、このスクリプトを使用して自動的に生成できます。現在のリリースに対応するタグと、前のリリースに対応する別のタグ（メンテナンスリリースは含まない）を受け入れます。たとえば、Spark 1.2.0をリリースする場合、現在のタグをv1.2.0-rc2に、前のタグをv1.1.0に設定します。最初のコントリビューターリストを生成した後、作成者名が正しく変換されていないという警告が表示される可能性が高くなります。これを修正するには、GitHubとJIRAから潜在的な置換を取得するこの他のスクリプトを実行します。例えば

$ cd release-spark/dev/create-release
# Set RELEASE_TAG and PREVIOUS_RELEASE_TAG
$ export RELEASE_TAG=v1.1.1
$ export PREVIOUS_RELEASE_TAG=v1.1.0
# Generate initial contributors list, likely with warnings
$ ./generate-contributors.py
# set JIRA_USERNAME, JIRA_PASSWORD, and GITHUB_API_TOKEN
$ export JIRA_USERNAME=blabla
$ export JIRA_PASSWORD=blabla
$ export GITHUB_API_TOKEN=blabla
# Translate names generated in the previous step, reading from known_translations if necessary
$ ./translate-contributors.py

さらに、大規模なパッチの開発者に対してより具体的なクレジットを与えたい場合は、次のコマンドを使用して大規模なパッチを特定できます。gitは異なるブランチにバックポートされたコミットを簡単に関連付けることができないため、以前のリリースからのコミットがカウントされないように特に注意する必要があります。

# Determine PR numbers closed only in the new release
$ git log v1.1.1 | grep "Closes #" | cut -d " " -f 5,6 | grep Closes | sort > closed_1.1.1
$ git log v1.1.0 | grep "Closes #" | cut -d " " -f 5,6 | grep Closes | sort > closed_1.1.0
$ diff --new-line-format="" --unchanged-line-format="" closed_1.1.1 closed_1.1.0 > diff.txt

# Grep expression with all new patches
$ EXPR=$(cat diff.txt | awk '{ print "\\("$1" "$2" \\)"; }' | tr "\n" "|" | sed -e "s/|/\\\|/g" | sed "s/\\\|$//")

# Contributor list
$ git shortlog v1.1.1 --grep "$EXPR" > contrib.txt

# Large patch list (300+ lines)
$ git log v1.1.1 --grep "$expr" --shortstat --oneline | grep -B 1 -e "[3-9][0-9][0-9] insert" -e "[1-9][1-9][1-9][1-9] insert" | grep SPARK > large-patches.txt

Spark Dockerイメージの作成とアップロード

apache/spark-dockerは、Spark Dockerイメージを公開するためのdockerfileとGithub Actionを提供します。

1. Spark Dockerfileをapache/spark-dockerリポジトリにアップロードするには、リンクを参照してください。
2. Spark Dockerイメージを公開する
   1. 公開ページにアクセスします。
   2. 「ワークフローを実行」をクリックします。
   3. 「SparkイメージのSparkバージョン」を選択し、「イメージを公開するかどうか」をクリックし、ターゲットレジストリとして「apache」を選択します。
   4. 「ワークフローを実行」ボタンをクリックして、イメージをApache dockerhubに公開します。

アナウンスを作成する

すべてが正常に機能したら（ウェブサイトのドキュメント、ウェブサイトの変更）、ウェブサイトにアナウンスを作成し、[ANNOUNCE] ...のような件名でメーリングリストにメールを送信します。アナウンスを作成するには、news/_postsの下に投稿を作成し、bundle exec jekyll buildを実行します。

お好みのアルコール飲料で乾杯し、Sparkのリリースおめでとうございます。