Homebrew/brew 維護人員指南

本文檔描述了 Homebrew/brew 儲存庫中幾個組件，維護人員了解這些組件會很有用，但對於大多數使用者和貢獻者來說，這些組件不一定要出現在文件檔中。

合併公關

合併使用 Homebrew/brew 儲存庫中的標準「合併」按鈕來保留歷史記錄和 GPG 承諾簽署。「壓縮並合併」和「變基並合併」按鈕已停用。

公關必須符合以下條件才能合併

至少獲得一位維護人員的核准。
通過 CI（持續整合）。這是強制性步驟。CI 失敗的公關絕不應該合併。有關 Homebrew/brew CI 的更多資訊，請參閱以下 CI 部分。

如果可能，公關也應該有 GPG 簽署的承諾（有關如何設定此項的說明，請參閱私人 ops 儲存庫）。

自動核准

為了確保非緊急公關有機會讓任何其他想要查看的維護人員看到並審查，所有公關在合併之前都需要核准。

CI

Homebrew/brew 中的每個公關都會執行一系列 CI 測試，以防止錯誤被引入。公關必須在合併之前通過 CI。

每個公關都會執行許多檢查。以下是各種檢查及其代表內容的快速清單

Vendor Gems / vendor-gems：除了 dependabot 公關之外，這會被跳過。它會更新 RBI 檔案以符合任何新增/變更的相依性。有關 RBI 檔案和類型檢查的更多資訊，請參閱使用 Sorbet 進行類型檢查。
Codecov / codecov/patch 和 codecov/project：這些會顯示公關的 Codecov 報告。有關 Codecov 的更多資訊，請參閱以下 brew tests 和 Codecov 部分。
CI / 供應商寶石：此檢查項目會檢查 Linux 上供應商寶石是否有需要提交至公關分支的變更。
CI / 測試預設公式 (Linux)：此檢查項目會在 Linux 上執行 brew test-bot，以確保其仍能如預期般運作。
CI / 語法：此檢查項目會先執行，以檢查公關是否通過 brew style 和 brew typecheck。如果此工作失敗，後續工作將不會執行。
CI / 點選語法：此檢查項目會對所有官方點選執行 brew style 和 brew audit（請注意，儘管此檢查項目會在 Linux 上執行，但它會檢查所有 cask 儲存庫）。
CI / docker：此檢查項目會建置新的 Homebrew Docker 映像，並將其部署到 GitHub 套件和 Docker Hub。
CI / 測試所有內容 (macOS)：此檢查項目會在 macOS 上執行多項檢查，包括 brew tests、brew update-tests、brew test-bot --only-formulae --test-default-formula、brew readall 和 brew doctor。
CI / 測試 (一般作業系統) 和 CI / 測試 (Linux)：這些檢查項目會在 Linux 上執行 brew tests，並搭配各種選項。
文件 CI / linting 和 rubydoc：這些檢查項目會檢查書面文件的文字和格式，並驗證 rubydoc API 文件是否可以順利建置。

請注意，此清單並非詳盡無遺，且可能會隨著時間而變更。

`brew tests` 和 Codecov

Codecov 會為每個公關產生涵蓋率報告，其結果會顯示為 CI 工作。這些報告可以在 Homebrew/brew 的 Codecov 頁面上公開查看。此外，在公關的「已變更檔案」標籤中，會出現註解，說明已新增哪些程式碼行，但未被 brew tests 命中。如果 Codecov 工作失敗，表示應該新增更多測試，以測試公關中新增的功能。

Codecov 應作為指示何時可能需要更多測試的指南，但對於每一行程式碼都有一個相關測試是不切實際的，特別是在測試需要緩慢的整合測試時。因此，必要時合併未通過 Codecov 檢查的 PR 是可以的，但如果可能的話應避免這樣做。

`brew tests` 和 BuildPulse

BuildPulse 會監控每次推送到 Homebrew/brew 的 CI 工作，以偵測不穩定的測試並追蹤它們的變化。這些報告可供 Homebrew 維護人員在 buildpulse.io 上取得，並會將每日摘要發布到 Slack 中的 #buildpulse-health。

BuildPulse 可作為指南，用於找出哪些不穩定的測試對 CI 套件造成最大的中斷。為了大幅改善建置的可靠性，我們可以先專注於最具破壞性的不穩定測試（即造成最多間歇性失敗的測試）。

為了協助找出特定不穩定測試的根本原因，buildpulse.io 會提供連結到最近的 CI 工作和提交，其中測試失敗，然後在未變更基礎程式碼的情況下通過。您可能想要查看該提交的程式碼，嘗試在本地重現失敗。您也可以在 buildpulse.io 上查看最近失敗的清單，以確定測試是否總是會以相同的方式失敗。

手冊頁和 Shell 自動完成

Homebrew 的手冊頁和 shell 自動完成會由 brew generate-man-completions 指令自動產生。歡迎貢獻者執行此指令並在 PR 中提交變更，但他們不必這麼做。如果他們沒有執行，則在原始 PR 合併後，@BrewTestBot 會自動開啟後續 PR 以進行必要的變更。如果變更看似正確，則可以立即合併這些後續 PR。

可以從「動作」標籤下的更新贊助者、維護人員、手冊頁和自動完成區段觸發工作流程，手動請求更新。按一下「執行工作流程」下拉式選單，然後按一下「執行工作流程」按鈕。如果有任何變更，系統將在短時間內開啟一個 PR。

Homebrew 文件