Homebrew/homebrew-core 維護人員指南

快速合併檢查清單

詳細的檢查清單可以在 下方 找到。這才是真正重要的

檢查依賴關係很重要，因為它們可能會永遠存在。沒有人會真正檢查它們是否必要。

盡可能依賴較少的東西。如果可能，請停用 X11 功能。例如，我們建置 Wireshark，但不建置繁重的 GUI。

Homebrew 關於 Unix 軟體。建置為 .app 的東西應該在 Homebrew Cask 中。

合併、重新設定基礎、挑選

對於大多數會修改配方的 PR，你可以簡單核准 PR，而 @BrewTestBot 會執行自動合併（含容器）。請參閱 針對維護人員的 BrewTestBot 以取得更多資訊。

某些 PR 可能不會在核准後由 @BrewTestBot 自動合併。這包括具有 new formula 和 automerge-skip 標籤的 PR。若要觸發這些 PR 的合併，請執行 brew pr-publish。

修改不需要容器或進行不需要拉取新容器的變更的配方的 PR 應使用 GitHub 的壓縮和合併或重新設定基礎和合併工作流程。

否則，您應該使用 brew pr-pull（或 rebase/cherry-pick 貢獻）。

不要 rebase，直到您最終 push。一旦 master 被推入，您就不能 rebase：您現在是一位維護人員！

Cherry-picking 會變更提交的日期，這有點糟糕。

不要 merge 不乾淨的分支。因此，如果有人仍在學習 git，而他們的分支充滿了無意義的合併，那麼就 rebase 並壓縮提交。我們的主要分支記錄應對其他人有幫助，而不是令人困惑。

只要一位維護人員批准並合併通過 CI 的新公式或更新公式的加入即可。但是，如果公式的加入或更新引起爭議，那麼加入它的維護人員將被期待回答請求並修復未來出現的問題。

如何在沒有 bottle 的情況下合併

以下是關於何時使用壓縮和合併與 rebase 和合併的指南。這些選項應僅用於 bottle 沒有受到影響的 PR。

  PR 修改單一公式 PR 修改多個公式
提交看起來不錯 rebase 和合併 或 壓縮和合併 rebase 和合併
提交需要處理 壓縮和合併 使用命令列手動合併

命名

名稱是最嚴格的項目，因為避免後續的名稱變更是可取的。

選擇一個最常見的專案名稱。例如，我們最初選擇 objective-caml，但我們應該選擇 ocaml。選擇人們在討論專案時會互相說的內容。

也由其他套件管理員（例如 Debian、Ubuntu）封裝的公式應命名一致（受 Homebrew 公式命名慣例造成的小差異影響）。

使用 tap 根目錄中 Aliases 內的符號連結，將其他名稱新增為別名。確保首頁上引用的名稱是其中之一，因為它可能不同，並包含底線和連字號等。

只要符合 需求，我們現在接受版本化公式。

測試

我們至少需要檢查它是否能建置。請使用 BrewTestBot 進行檢查。

如果可能，請驗證公式是否有效。如果你無法判斷（例如，如果它是一個函式庫），請相信原始貢獻者；它對他們來說有效，因此很有可能沒有問題。如果你不是相關工具的專家，你無法真正評估公式是否正確安裝了程式。在某個時間點，會有專家出現，大聲抱怨它無法運作，然後修復它。這就是開源軟體的運作方式。理想情況下，請要求 test do 區塊來測試功能是否持續可用。

如果公式使用儲存庫，則 url 參數應具有標籤或版本。 url 具有版本，且穩定（尚未實作！）。

不要合併任何 brew test 失敗的公式更新。如果 test do 區塊失敗，則需要修復它。這可能涉及用更可靠的測試取代更複雜的測試。這是可以接受的：假陽性優於假陰性，因為我們不希望教導維護人員合併紅色的 PR。如果測試失敗被認為是 Homebrew/brew 或 CI 系統中的錯誤，則必須修復該錯誤，或在公式中解決該錯誤以產生通過的測試，才能合併 PR。

重複

我們現在接受 macOS 附帶的軟體，只要它使用 keg_only :provided_by_macos 預設為僅 keg。

移除公式

公式

不應從 Homebrew 中移除。此規則的例外是 版本化公式，對其使用率有更高的標準，且特定公式的最大版本數目有限。

有關廢棄、停用和移除公式的更多資訊，請參閱 廢棄、停用和移除公式 頁面。

詳細合併檢查清單

以下檢查清單旨在協助維護人員決定是否合併、要求變更或關閉 PR。除了 可接受的公式 要求之外，它還為貢獻者帶來更高的透明度。

常見的建置失敗和處理方式

測試錯誤

「未定義對 ... 的參照」

當傳遞給 gcc 的參數順序錯誤時，可能會出現此錯誤。

來自 libmagic 配方的範例

==> brew test libmagic --verbose
Testing libmagic
==> /usr/bin/gcc -I/home/linuxbrew/.linuxbrew/Cellar/libmagic/5.38/include -L/home/linuxbrew/.linuxbrew/Cellar/libmagic/5.38/lib -lmagic test.c -o test
/tmp/ccNeDVRt.o: In function `main':
test.c:(.text+0x15): undefined reference to `magic_open'
test.c:(.text+0x4a): undefined reference to `magic_load'
test.c:(.text+0x81): undefined reference to `magic_file'
collect2: error: ld returned 1 exit status

解決方案

if OS.mac?
  system ENV.cc, "-I#{include}", "-L#{lib}", "-lmagic", "test.c", "-o", "test"
else
  system ENV.cc, "test.c", "-I#{include}", "-L#{lib}", "-lmagic", "-o", "test"
end

有關為何會發生此情況的說明，請閱讀 Ubuntu 11.04 工具鏈文件。

暫存分支

摘要

一些配方（例如 Python、OpenSSL、ICU、Boost）有大量的依賴項。這使得更新這些配方（或其依賴項）變得困難，因為標準程序涉及在單一拉取請求中更新大量配方。可以大幅簡化此程序的替代程序是使用暫存分支。

使用暫存分支的想法是將更新合併並將受影響配方的套件發布到非預設分支。這允許以較小的公關方式逐步完成工作，而不是在一個觸及許多配方的巨大公關中完成。當暫存分支準備好時，可以將其合併到 master/預設分支。

在使用暫存分支之前，有一個重要的缺點需要考慮：一旦將套件更新合併到暫存分支，就非常困難將其取回。這通常涉及刪除上傳的套件，偶爾需要 Homebrew GitHub 組織的所有者一次刪除一個上傳的套件。

如何使用暫存分支

以下是使用暫存分支的粗略說明

  1. 在 Homebrew/homebrew-core 中建立暫存分支。暫存分支的名稱必須以根配方的名稱開頭，後跟 -，並以 -staging 結尾。你可以省略 @ 和版本化配方後面的任何內容（例如 icu4c-staging、openssl-migration-staging、python@3.12-staging）。查看 程式碼可能會有所幫助，該程式碼解析分支名稱以檢查公關是否針對暫存分支。

  2. 在 homebrew-core 中開啟議題，邀請貢獻者協助。務必包含如何執行操作的說明，以及需要更新的配方清單。請參閱 Homebrew/homebrew-core#134251 以取得範例。

  3. 開啟一個將暫存區分支合併至 master 分支的草稿 PR。這可讓您追蹤迄今為止完成的工作。您可能希望套用 no long build conflict 標籤至這個 PR，以避免將衝突變更合併至 master 分支。

  4. 開啟針對暫存區分支的 PR，以更新受影響的配方。每個 PR 應盡可能變更少數配方。針對暫存區分支的典型 PR 一次只會更新一個配方。暫存區分支 PR 可使用與針對 master 分支的 PR 相同的程序進行合併。理想情況下，這些 PR 應根據相依圖以 拓撲順序 開啟，但我們目前沒有良好的工具來產生拓撲排序。（歡迎協助。）

  5. 針對暫存區分支的 PR 標籤 staging-branch-pr 標籤，以利追蹤和檢閱。（待辦事項：為 homebrew-core 新增一些自動化功能。）

  6. 監控您在步驟 3 中建立的草稿 PR，以了解合併衝突。如果您遇到合併衝突，您必須在將 master 分支合併至暫存區分支的暫存區分支 PR 中解決這些衝突。

  7. 當暫存區分支準備好合併至 master 時，將草稿 PR 標記為準備好檢閱，並將其合併至 master 分支。您的 PR 可能會在合併佇列中花費很長一段時間等待瓶子擷取測試執行。

如需暫存區分支使用範例，請參閱標籤為 openssl-3-migration-staging、Homebrew/homebrew-core#134260 或 Homebrew/homebrew-core#133611 的 homebrew-core PR。

最後：雖然暫存區分支的使用在兩個使用案例中表現得非常好（請參閱前一段中連結的 PR），但上述程序並非完美。我們非常歡迎改善建議。

Fork me on GitHub