準備 Spark 發布

背景

Spark 中的發布管理員角色表示您負責幾項不同的工作

  1. 準備您的設定
  2. 準備發行候選版本
    1. 建立發行分支
    2. 通知社群時間
    3. 與元件負責人合作清理 JIRA
    4. 在該分支中進行程式碼變更,並執行必要的版本更新
  3. 執行發布的投票流程
    1. 使用自動化工具建立發行候選版本
    2. 呼籲投票並分類問題
  4. 完成並張貼發布
    1. 更新 Spark 網站
    2. 撰寫發布說明
    3. 宣布發布

準備您的設定

如果您是新的發布管理員,可以從以下文件閱讀流程

準備 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-keysgpg --import 指令將您的秘密金鑰傳輸到該機器。

安裝 Docker

建立發行候選版本的指令碼是透過 docker 執行的。在執行這些指令碼之前,您需要安裝 docker。請確保您可以以非 root 使用者身分執行 docker。請參閱 https://docker-docs.dev.org.tw/install/linux/linux-postinstall 以取得更多詳細資料。

準備 Spark 以進行發布

準備發布的主要步驟是建立發行分支。這是透過標準 Git 分支機制完成的,並且應該在建立分支後向社群宣布。

建立候選版本

若這不是第一個候選版本,請確認自上次候選版本後已解決的 JIRA 問題已標記為 已解決,且 目標版本 已設定為此版本。

若要追蹤任何針對此版本發行的待處理公關問題,請使用類似此查詢在 JIRA 中建立篩選條件 project = SPARK AND "Target Version/s" = "12340470" AND status in (Open, Reopened, "In Progress")

若要使用目標版本字串值,請尋找與該目標版本相關的現有問題,並點選版本(例如,尋找針對 2.2.1 的問題,並點選其目標版本欄位的版本連結)以找出對應於版本的數字值。

git log 驗證這些問題是否實際上已包含在新候選版本中。檢查標記有 release-notes 標籤的 JIRA 問題,並確認這些問題已記錄在網站上針對重大變更的相關遷移指南或後續的版本新聞中。

建立候選版本有 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 爬蟲器的組態
  • 從鏡像網路中移除舊版本
  • 更新 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://www.apache.org/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 的文件,這是您最後一次備份的機會。這將用於在接下來的步驟中將文件上傳到網站。在移除目錄前,請從 svn 中查看文件。

在投票通過並將已核准的 RC 移到發佈儲存庫後,您應從暫存儲存庫中刪除 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 爬蟲器的組態

Spark 文件網站 上的搜尋方塊利用 Algolia Crawler。在發佈前,請使用 Algolia Crawler 管理員主控台,為 Apache Spark 更新爬蟲設定,並使用新版本。如果您無法存取設定,請聯絡 Gengliang WangXiao 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 上建立一個短網址,登入您的 Apache 帳戶,並將 ID 選取為類似 spark-2.1.2 的內容。在 releases/_posts 下建立一個新的發行文章,以包含此短網址。文章的日期應為您建立文章的日期。

然後執行 bundle exec jekyll build 以更新 site 目錄。

考慮到 Pull Request 會很大,請將程式碼變更和產生的 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 提供 Docker 檔案和 GitHub Action,用於發布 Spark Docker 映像。

  1. 上傳 Spark Docker 檔案至 apache/spark-docker 儲存庫,請參閱 連結
  2. 發布 Spark Docker 映像
    1. 進入 發布頁面
    2. 按一下「執行工作流程」。
    3. 選取「Spark 映像的 Spark 版本」,按一下「是否發布映像」,選取「apache」作為目標登錄檔。
    4. 按一下「執行工作流程」按鈕,將映像發布至 Apache dockerhub。

建立公告

一旦一切都正常運作(網站文件、網站變更),請在網站上建立公告,然後寄送電子郵件至郵件清單,主旨看起來類似於 [公告] ...。要建立公告,請在 news/_posts 下建立一則貼文,然後執行 bundle exec jekyll build

享用您選擇的成人飲料,並恭喜您發布 Spark。

最新消息

檔案