如何開啟 Homebrew Pull Request

Homebrew 貢獻者使用以下指令在 GitHub 上設定 Homebrew Git 儲存庫的分支，建立新的分支，並為該分支中的變更建立 GitHub pull request（「PR」）。

您想要進行的變更類型會影響您需要將 pull request 傳送至 Homebrew 哪個主要儲存庫。如果您想要提交變更至 Homebrew 的核心程式碼（brew 實作），您應該在 Homebrew/brew 上開啟 pull request。如果您想要提交變更至配方，您應該在 homebrew/core tap 上開啟 pull request，而對於 cask，您應該在 homebrew/cask tap 或其他 官方 tap 上開啟 pull request，具體取決於配方類型。

提交現有配方的最新版本

  1. 使用 brew bump-formula-pr 使用單一指令執行所有動作（例如分岔、提交、推播）。執行 brew bump-formula-pr --help 以深入了解。

提交現有 cask 的最新版本

  1. 使用 brew bump-cask-pr 使用單一指令執行所有動作（例如分岔、提交、推播）。執行 brew bump-cask-pr --help 以深入了解。

設定您自己的 Homebrew 儲存庫分支

核心 brew 程式碼 pull request

  1. 在 GitHub 上分岔 Homebrew/brew 儲存庫.
    • 這會建立一個您可以推播的個人遠端儲存庫。這是必要的，因為只有 Homebrew 維護人員有權限推播至主要儲存庫。

  2. 變更至包含 Homebrew 安裝的目錄

    cd "$(brew --repository)"

  3. 將您可推播的分岔儲存庫新增為新的遠端

    git remote add <YOUR_USERNAME> https://github.com/<YOUR_USERNAME>/brew.git
    • <YOUR_USERNAME> 是您的 GitHub 使用者名稱，而非您的本機機器使用者名稱。
  1. 在 GitHub 上 Fork Homebrew/homebrew-core 儲存庫.
    • 這會建立一個您可以推播的個人遠端儲存庫。這是必要的，因為只有 Homebrew 維護人員有權限推播至主要儲存庫。

  2. 點選 (下載儲存庫的本地複製) 核心 Homebrew 配方的儲存庫

    brew tap --force homebrew/core

  3. 變更至包含 Homebrew 配方的目錄

    cd "$(brew --repository homebrew/core)"

  4. 將您可推播的分岔儲存庫新增為新的遠端

    git remote add <YOUR_USERNAME> https://github.com/<YOUR_USERNAME>/homebrew-core.git
    • <YOUR_USERNAME> 是您的 GitHub 使用者名稱，而非您的本機機器使用者名稱。
  1. 在 GitHub 上 Fork Homebrew/homebrew-cask 儲存庫.
    • 這會建立一個您可以推播的個人遠端儲存庫。這是必要的，因為只有 Homebrew 維護人員有權限推播至主要儲存庫。

  2. 點選 (下載儲存庫的本地複製) 核心 Homebrew casks 的儲存庫

    brew tap --force homebrew/cask

  3. 變更至包含 Homebrew casks 的目錄

    cd "$(brew --repository homebrew/cask)"

  4. 將您可推播的分岔儲存庫新增為新的遠端

    git remote add <YOUR_USERNAME> https://github.com/<YOUR_USERNAME>/homebrew-cask.git
    • <YOUR_USERNAME> 是您的 GitHub 使用者名稱，而非您的本機機器使用者名稱。

從新分支建立您的 pull request

若要在新分支上進行變更並提交以供審查，請執行下列步驟建立 GitHub pull request

  1. 查看 master 分支

    git checkout master

  2. 擷取 master 分支的新變更

    brew update

  3. 從最新的 master 分支建立新分支

    git checkout -b <YOUR_BRANCH_NAME> origin/master
  4. 進行您的變更。對於配方或 casks，請使用 brew edit 或您最喜愛的文字編輯器，並遵循 配方食譜 或 Cask 食譜 中的所有準則。
    • 如果配方中有一個 bottle do 區塊，請勿移除或變更它；當我們合併您的 PR 時，我們會更新它。

  5. 執行下列指令測試您的變更，並確保它們全部通過且沒有問題。對於變更的配方和 casks，請務必在安裝變更的配方/cask 後執行 brew audit 步驟。

    brew tests
HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source <CHANGED_FORMULA|CHANGED_CASK>
brew test <CHANGED_FORMULA|CHANGED_CASK>
brew audit --strict --online <CHANGED_FORMULA|CHANGED_CASK>
  6. 為每個變更的配方建立一個單獨的提交，並使用 git add 和 git commit。每個配方的提交都必須壓縮。
    • 請注意，我們對簡單版本更新所需的提交訊息格式為“<FORMULA_NAME> <NEW_VERSION>”，例如“source-highlight 3.1.8”。

  7. 將您新提交的分支上傳至您的 fork

    git push --set-upstream <YOUR_USERNAME> <YOUR_BRANCH_NAME>
  8. 前往相關儲存庫 (例如 https://github.com/Homebrew/brew、https://github.com/Homebrew/homebrew-core 等)，並建立一個 pull request，以要求審查並合併您已推送到分支的提交。說明變更的必要性，以及如果要修正錯誤，請說明如何重現錯誤。請務必完成您的新 PR 中出現的檢查清單中的每個步驟。
  9. 等待 Homebrew 維護人員的回饋或合併。我們通常會在幾天內回應所有 PR，但可能會需要長達一週的時間，具體取決於維護人員的工作負載。

謝謝您！

後續追蹤

妥善回應回饋

  1. 對於任何你不了解的事項，請尋求澄清；對於任何你不知道如何執行的事項，請尋求協助。
  2. 如果你已提供所有要求的變更/資訊，且在一個星期後仍未合併，請在你的 pull request 上發布留言。如果你遇到困難且需要協助，請在你的 pull request 上發布留言。
    • PR 上的 needs response 標籤表示 Homebrew 維護人員需要你回應先前的留言。
  3. 除非另有要求，否則請將討論保留在 pull request 中（即不要私下寄電子郵件給維護人員）。
  4. 請勿在已關閉的 pull request 中繼續討論。
  5. 請勿與 Homebrew 維護人員爭論。你可能會不同意，但除非他們改變心意，否則請實作他們的要求。最終，他們控制 Homebrew 中包含的內容，因為他們必須支援所做的任何變更。

根據回饋進行變更

  1. 再次查看你的分支

    git checkout <YOUR_BRANCH_NAME>
  2. 進行任何要求的變更，並使用 git add 和 git commit 將其提交。

  3. 將新的提交壓縮成每個公式一個提交

    git rebase --interactive origin/master
    • 如果你正在為單一公式處理 PR，git commit --amend 是在進行時保持提交壓縮的便捷方式。

  4. 推送到你的遠端分支和 pull request

    git push --force

一旦所有回饋都已處理，且這是我們想要納入的變更（我們會納入大部分變更），我們就會將你的變更新增到 Homebrew。請注意，由於我們合併貢獻的方式，PR 狀態可能會顯示為「已關閉」而非「已合併」。不用擔心：你仍會在實際合併的提交中獲得作者身分。

做得好，你現在是 Homebrew 貢獻者了！

Fork me on GitHub