如何公開發佈 LLVM

簡介

本文件包含有關成功發佈 LLVM 的資訊，包括子專案：例如 clang 和 compiler-rt。發佈經理有責任確保發佈高品質的 LLVM 版本。

如果您正在尋找有關如何測試候選版本並建立二進制套件的文件，請參閱 如何驗證新版本。

發佈時間表

LLVM 按照時間表發佈，主要版本大約每 6 個月發佈一次。在主要版本之間，可能會有點版本。發佈經理將根據社群的反饋決定是否以及何時發佈點版本。通常，如果穩定分支中有大量錯誤修復或發現影響大量使用者的嚴重錯誤，則應發佈點版本。

除非另有說明，否則點版本將遵循與主要版本相同的程序。

年度發佈時間表

以下是 LLVM 的年度發佈時間表。這僅供參考，發佈經理無需完全遵循此時間表。版本應在星期二標記。

版本

大約日期

發佈分支：偶數版本

1 月第 4 個星期二

發佈分支：奇數版本

7 月第 4 個星期二

X.1.0-rc1

分支後 3 天。

X.1.0-rc2

分支後 2 週。

X.1.0-rc3

分支後 4 週

X.1.0-final

分支後 6 週

X.1.1

分支後 8 週

X.1.2

分支後 10 週

X.1.3

分支後 12 週

X.1.4

分支後 14 週

X.1.5

分支後 16 週

X.1.6（如果需要）

分支後 18 週

發佈流程摘要

  • 向 LLVM 社群宣佈發佈時間表並更新網站。請至少在 -rc1 版本發佈前 3 週完成此操作。

  • 建立發佈分支並開始發佈流程。

  • 發送候選版本的原始碼以進行第一輪測試。測試持續 6 週。在第一輪測試期間，應修復發現的所有回歸。修補程式從主線合併到發佈分支。此外，所有功能都需要在此期間完成。在第一輪測試結束時未完成的所有功能將從版本中移除或停用。

  • 產生並發送第二個候選版本的原始碼。在此測試階段，只會修復發現的*嚴重*錯誤。合併的修補程式引入的任何錯誤都將得到修復。如果是這樣，則需要進行第三輪測試。

  • 版本資訊已更新。

  • 終於發布了！

  • 向 LLVM 社群宣布錯誤修復版本發布時程，並更新網站。

  • 每兩週發布一次錯誤修復版本，直到 X.1.5 或 X.1.6（如有必要）。

發布流程

發布管理工作

本節描述開始發布流程需要完成的一些管理工作。具體來說，它涉及

  • 更新版本號碼，

  • 建立發布分支，以及

  • 標記發布候選版本，供發布團隊開始測試。

建立發布分支

使用以下步驟從 Git 主幹分支：

  1. 提醒開發人員即將進行發布分支，並避免提交可能會破壞建置的修補程式。例如，新功能、正在進行中工作的巨大修補程式、類型系統的全面檢查、令人興奮的全新 TableGen 功能等。

  2. 通過檢查夜間測試人員和建置機器人的結果，確認當前的 Git 主幹處於良好狀態。

  3. 將主幹中的版本提升至 N.0.0git，並使用 llvmorg-N-init 標記提交。如果 X 是要發布的版本，則 N 是 X + 1。

$ git tag -sa llvmorg-N-init

  1. 清除主幹中的版本資訊。

  2. 從版本提升之前的最後一個已知良好修訂版建立發布分支。分支的名稱為 release/X.x，其中 X 是主要版本號碼，x 只是字母 x。

  3. 在新建立的發布分支上，立即將版本提升至 X.1.0git（其中 X 是分支的主要版本）。

  4. 所有標籤和分支都需要在 llvm/llvm-project 和 llvm/llvm-test-suite 儲存庫中建立。

更新 LLVM 版本

建立 LLVM 發布分支後，使用 llvm/utils/release/bump-version.py 中的腳本更新發布分支的版本。

標記 LLVM 發布候選版本

標記發布候選版本

$ git tag -sa llvmorg-X.Y.Z-rcN

預先打包的原始碼壓縮檔將通過 GitHub 上的「發布原始碼」工作流程自動產生。此工作流程將建立一個包含所有發行壓縮檔和證明文件的成品。發行管理員應下載成品，驗證壓縮檔，簽署，然後將其上傳到發行頁面。

$ unzip artifact.zip
$ gh auth login
$ for f in *.xz; do gh attestation verify --owner llvm $f && gpg -b $f; done

壓縮檔、發行二進位檔或任何其他發行成品都必須上傳到 GitHub。這可以使用 utils/release 中的 github-upload-release.py 腳本完成。

$ github-upload-release.py upload --token <github-token> --release X.Y.Z-rcN --files <release_files>

建置二進位發行版

創建二進位發行版需要遵循 這裡 的說明。

該過程將執行 Release+Asserts 和 Release 版本建置，但僅打包 Release 版本以上傳。您應該使用 Release+Asserts sysroot（通常位於 final/Phase3/Release+Asserts/llvmCore-3.8.1-RCn.install/ 下）進行測試套件和執行時間基準測試，以確保沒有嚴重問題通過網路。對於編譯時間基準測試，請使用 Release 版本。

您需要的工具的最低版本要求 這裡

發行資格標準

沒有正式的發行資格標準。由發行管理員決定何時發布版本。發行管理員在決定是否發布版本時，應注意社群測試的結果、未解決錯誤的數量以及回歸的數量。

社群重視基於時間的發布，因此除非存在嚴重的問題，否則不應將發布延遲太久。在大多數情況下，唯一足以阻止發布的錯誤類型是先前版本的重大回歸。

官方測試

社群中的一些開發人員已經投入時間來驗證候選版本，並自願成為每個架構的官方版本測試人員。

這些人將測試、生成並將官方二進位文件上傳到伺服器，並且將是發布進行所需的最低限度測試。

這顯然不會涵蓋所有作業系統和發行版，因此額外的社群驗證非常重要。但是，如果在發布之前沒有收到社群意見回饋，則所有報告的錯誤都必須在下一個穩定版本中解決。

官方發行管理員為

官方版本測試人員是從社群中招募的志願者，他們一直在為其目標/作業系統驗證和發布二進位文件。要聯繫他們，您應該在 Discourse 論壇（專案基礎架構 - 版本測試人員） 上發布。

官方測試人員列表位於 LLVM 儲存庫的 RELEASE_TESTERS.TXT 文件中。

社群測試

完成所有測試並提交適當的錯誤後，候選版本壓縮檔將發布到網站上，並通知 LLVM 社群。

我們要求所有 LLVM 開發人員以以下任何方式測試版本

  1. 下載 llvm-X.Y、llvm-test-X.Y 和相應的 clang 二進位文件。建置 LLVM。執行 make check 和完整的 LLVM 測試套件 (make TEST=nightly report)。

  2. 下載 llvm-X.Y、llvm-test-X.Y 和 clang 原始碼。編譯所有內容。運行 make check 和完整的 LLVM 測試套件 (make TEST=nightly report)。

  3. 下載 llvm-X.Y、llvm-test-X.Y 和適當的 clang 二進制文件。使用它為您的平台構建完整程序（例如 Chromium、Firefox、Apache）。

  4. 下載 llvm-X.Y、llvm-test-X.Y 和適當的 clang 二進制文件。使用它構建*您的*程序，並檢查一致性和性能回歸。

  5. 如果您的平台與官方支持的平台*不同*，請運行發布流程，並且僅在該架構的官方發布測試人員未報告錯誤時才回報錯誤。

我們還要求操作系統發行版發布管理員使用每個發布版的首個候選版本測試他們的軟體包，並在 GitHub 上報告任何*新的*錯誤。如果可以使用未修補的發布候選版本的原始碼（而不是發行版自己的構建）重現該錯誤，則其優先級應為發布阻止程序。

在第一輪測試期間，所有回歸都必須在發布第二個候選版本之前修復。

在後續階段，測試僅用於確保先前合併的錯誤修復程序沒有產生新的重大問題。*現在不是解決其他不相關錯誤的時候！*如果沒有合併任何修補程序，則認為發布版已準備就緒，發布管理員可以進入下一階段。

回報回歸

在測試期間發現的每個回歸（根據上述標準）都應在 GitHub 中的錯誤報告中填寫，並添加到發布里程碑中。

如果無法重現錯誤，或者不再是阻止程序，則應從里程碑中移除。調試可以繼續，但在主幹分支上進行。

回溯請求

有關請求回溯到穩定分支的說明，請參閱此處。

對發布版的錯誤報告進行分類

本節描述如何對錯誤報告進行分類

  1. 搜索具有發布里程碑但尚未添加到“發布狀態” GitHub 專案的錯誤

    https://github.com/llvm/llvm-project/issues?q=is%3Aissue+milestone%3A%22LLVM+14.0.5+Release%22+no%3Aproject+

    在此查詢中，將 14.0.5 替換為目標發布里程碑的版本。

    將這些錯誤添加到“發布狀態”專案中。

  2. 導航至發布狀態專案以查看正在考慮包含在發布版中的錯誤清單。

  3. 檢查每個錯誤，首先檢查它是否已在主分支中修復。如果已修復，請將其狀態更新為“需要拉取請求”，並使用 /cherry-pick 或 /branch 註釋為修復程序創建拉取請求（如果尚未執行此操作）。

  4. 如果一個錯誤已經被修復，並且已經創建了一個用於回溯移植的拉取請求，那麼請將其狀態更新為“需要審查”，並通知一位知識淵博的審查者。通常，您會希望通知在 Phabricator 中批准此修補程式的人員，但您可以自行判斷誰是合適的審查者。一旦您確定了審查者，請將問題分配給他們，並在評論中提及他們（例如 @用戶名），詢問他們該修補程式是否可以安全地回溯移植。您還應該自己檢查錯誤，以確保其符合提交到發布分支的要求。

  5. 一旦錯誤被審查，請添加 release:reviewed 標籤，並將問題的狀態更新為“需要合併”。檢查與該問題相關聯的拉取請求。如果所有測試都通過，則可以合併拉取請求。如果沒有，請在問題上添加評論，要求其他人查看失敗的原因。

  6. 合併拉取請求後，請使用 llvm/utils/git/sync-release-repo.sh 腳本將其推送到正式的發布分支。

    然後在問題中添加一條評論，說明已合併修復程式以及發布分支中的 git 哈希值。將 release:merged 標籤添加到問題並關閉它。

發布修補程式規則

以下是關於修補發布分支的規則

  1. 應用於發布分支的修補程式只能由發布管理員、官方發布測試人員或經發布管理員批准的代碼所有者應用。

  2. 鼓勵發布管理員在批准修補程式之前徵求代碼所有者的批准，但這並非強制性要求。如果沒有代碼所有者或代碼所有者無法聯繫，則發布管理員可以徵求修補程式審查者或該領域活躍的其他開發人員的批准。

  3. 在 RC1 之前 修補程式應限於錯誤修復、重要的優化改進或完成在分支創建之前開始的功能。與所有階段一樣，發布管理員和代碼所有者可以拒絕被認為過於侵入性的修補程式。

  4. 在 RC2 之前 修補程式應限於錯誤修復或被認為非常安全的後端特定改進。

  5. 在 RC3/最終主要版本之前 修補程式應限於嚴重的錯誤或回歸。

  6. 錯誤修復版本 修補程式應限於錯誤修復或非常安全和關鍵的性能改進。修補程式必須與之前的版本保持 API 和 ABI 相容性。

發布最終任務

發布過程的最後階段包括標記“最終”發布分支、更新引用該版本的文檔以及更新演示頁面。

更新文檔

檢查發布分支中的文檔，並確保其是最新的。“發布說明”必須更新，以反映新功能、錯誤修復、新的已知問題以及支持平台列表中的更改。“入門指南”應更新，以反映 Subversion 中可用的新版本號標籤以及基本系統要求的變化。

標記 LLVM 最終版本

標記最終版本的源代碼

$ git tag -sa llvmorg-X.Y.Z
$ git push https://github.com/llvm/llvm-project.git llvmorg-X.Y.Z

更新 LLVM 網站

必須在發送發布公告之前更新網站。以下是需要做的事情

  1. 從 GitHub 檢出 www-releases 模組。

  2. 在 releases 目錄中創建一個新的子目錄 X.Y.Z。

  3. 將 llvm/docs 和 LICENSE.txt 檔案複製並提交到這個新目錄。

  4. 使用 GitHub 上發佈的二進制檔案的連結更新 releases/download.html 檔案。

  5. 使用新的發佈版本更新 releases/index.html，並連結到發佈文件。

  6. 將更改推送至 www-releases 儲存庫後，具有管理員權限的人員必須登入 prereleases-origin.llvm.org 並手動將新的更改提取到 /data/www-releases/。這是網站提供服務的地方。

  7. 最後，檢查 llvm-www 儲存庫並更新首頁（index.html 和側邊欄），以指向新的發佈版本和發佈公告。

發佈公告

所有發佈任務完成後，在 公告類別 中建立新的貼文。對於 X.1.0 發佈版本，請務必在貼文中包含指向發佈說明的連結。對於 X.1.1+ 發佈版本，請使用以下命令產生更新日誌並將其添加到貼文中。

$ git log --format="- %aN: [%s (%h)](https://github.com/llvm/llvm-project/commit/%H)" llvmorg-X.1.N-1..llvmorg-X.1.N

發佈公告後，請在 llvm 首頁（來自 llvm-www 儲存庫）的「發佈電子郵件」區段中新增指向公告的連結。