LLVM 公開發布指南

簡介

本文檔包含關於成功向公眾發布 LLVM（包括子專案，例如 clang 和 compiler-rt）的資訊。發布管理員有責任確保發布高品質的 LLVM 版本。

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

發布時程表

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

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

年度發布時程

以下是 LLVM 的年度發布時程表。這僅供參考，發布管理員不一定需要完全遵循。版本應在星期二標記。

發布版本	約略日期
發布分支：偶數版本	一月第四個星期二
發布分支：奇數版本	七月第四個星期二
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. 通過檢查 nightly tester 和 buildbot 結果，驗證當前的 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

預先封裝的原始碼 tarball 將通過 GitHub 上的「Release Sources」工作流程自動產生。此工作流程將建立一個包含所有發布 tarball 和工件證明的工件。發布管理員應下載工件、驗證 tarball、簽署它們，然後將它們上傳到發布頁面。

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

Tarball、發布二進制檔案或任何其他發布工件必須上傳到 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 版本。

您需要的最少工具版本在此處

發布資格標準

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

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

官方測試

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

這些人將負責測試、產生和上傳官方二進制檔案到伺服器，並且將是發布繼續進行必要的最低限度測試。

這顯然不會涵蓋所有作業系統和發行版，因此額外的社群驗證非常重要。但是，如果在發布版本之前未獲得社群的輸入，則所有報告的錯誤都將歸到下一個穩定版本中。

官方發布管理員為

• 偶數版本：Tom Stellard (tstellar@redhat.com)

• 奇數版本：Tobias Hieta (tobias@hieta.se)

官方發布測試人員是從社群中自願加入的，並且持續驗證和發布其目標/作業系統的二進制檔案。要聯繫他們，您應該在Discourse 論壇（Project Infrastructure - Release Testers）上發帖。

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

社群測試

完成所有測試並提交適當的錯誤後，候選版本 tarball 將被放置在網站上，並通知 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. 搜尋具有發布里程碑但尚未添加到「Release Status」github 專案的錯誤

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

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

   將這些錯誤添加到「Release Status」專案。

2. 導航到Release Status 專案以查看正在考慮用於發布的錯誤列表。

3. 查看每個錯誤，首先檢查它是否已在主線中修復。如果已修復，則將其狀態更新為「Needs Pull Request」，並在使用 /cherry-pick 或 /branch 註解尚未完成的情況下，為修復建立拉取請求。

4. 如果錯誤已修復並已建立拉取請求以進行反向移植，則將其狀態更新為「Needs Review」並通知一位知識淵博的審閱者。通常，您會希望通知在 Phabricator 中批准修補程式的人員，但您可以根據自己的判斷來決定誰是合適的審閱者。確定審閱者後，將問題分配給他們，並在註解中提及他們（即 @username），並詢問他們修補程式是否可以安全地反向移植。您還應該自己審閱錯誤，以確保其符合提交到發布分支的要求。

5. 錯誤經過審閱後，添加 release:reviewed 標籤，並將問題的狀態更新為「Needs Merge」。檢查與問題關聯的拉取請求。如果所有測試都通過，則可以合併拉取請求。如果沒有通過，則在問題上添加註解，要求有人查看失敗情況。

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

   然後在問題中添加註解，說明修復已合併，並附帶發布分支的 git 哈希值。將 release:merged 標籤添加到問題並關閉它。

發布修補程式規則

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

1. 應用於發布分支的修補程式只能由發布管理員、官方發布測試人員或維護人員在獲得發布管理員的批准後應用。

2. 鼓勵但不要求發布管理員在批准修補程式之前獲得維護人員的批准。如果沒有可聯繫的維護人員，則發布管理員可以向修補程式審閱者或該領域的其他活躍開發人員請求批准。

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

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

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

6. 錯誤修復版本 修補程式應僅限於錯誤修復或非常安全且關鍵的效能改進。修補程式必須保持與 X.1.0 版本的 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 儲存庫）的「Release Emails」部分添加公告連結。