Homebrew/brew 维护者实战指南：PR 评审、合并门槛与自动化批准流水线

本文以 Homebrew/brew 仓库的维护者指南 docs/Maintainer-Guidelines.md 为主体，系统梳理 Homebrew 维护者的 PR 评审决策规范、合并前置条件、Revert 与 24 小时评审窗口、沟通准则等核心协作规则，并结合仓库内 .github/workflows/approve-stale-lead-maintainer-prs.yml 与 .github/scripts/approve_stale_lead_maintainer_prs.rb 的真实源码，剖析“自动批准过期 lead maintainer PR”流水线的十项判定条件。读完后，你将掌握一套可落地的开源项目 PR 评审方法论，以及一条把“人工审批瓶颈”用确定性规则自动化掉的完整工程实现。

1. 适用对象与维护团队分工

Homebrew 维护者指南开篇就明确了读者定位：本指南写给维护者（maintainers）——即拥有 Homebrew 仓库写权限、负责合并他人贡献的特殊角色。文档同时提示：如果你只是普通贡献者，应该去看 Formula Cookbook 或 Cask Cookbook，而不是本文。

所有维护者被鼓励参与项目的各个部分，但实践中会自然聚集成四个主要团队：

团队	维护的仓库	详细指南
brew 维护者	Homebrew/brew（本仓库）	Homebrew/brew Maintainer Guide
Core 维护者	Homebrew/homebrew-core	Homebrew/homebrew-core Maintainer Guide
Linux 维护者	Homebrew/homebrew-core（Linux 方向）	同上 core 指南
Cask 维护者	Homebrew/homebrew-cask	Homebrew/homebrew-cask Maintainer Guide

原文特别强调，这些文档的定位是指导原则（guiding principles）而非硬性条例：维护者可以根据贡献者的熟练程度与过往贡献记录，自行决定是“要求修改”还是“直接帮一把”。指南还引用了 Maintainers: Avoiding Burnout 中的第 3 条原则——团队优先保障维护者而不是用户，以避免志愿者倦怠；如果想修改或讨论其中任何一条规范，正确做法是提交一个 PR 来提出变更。

2. Mission：所有技术决策的基准线

docs/Maintainer-Guidelines.md 用一段话定义了 Homebrew 的使命，这也是维护者做取舍时的最高依据：

Homebrew is the package manager for everywhere. Its primary goal is to be useful to as many people as possible, while remaining maintainable to a professional, high standard by a small group of volunteers.

拆解成三条可操作的判断标准：

1. 尽可能对更多人有用，同时必须由一小群志愿者以专业高标准长期可维护地运营；
2. 在 macOS 上，尽可能利用系统特性，与 macOS 和 Apple 生态“融为一体”；
3. 在 Linux 和 Windows 上，尽可能自包含（self-contained），减少对系统环境的依赖。

评审中遇到“该不该支持某个特性/依赖”的争议时，回落到这三条基准比争论个人偏好更可靠。

3. PR 评审的四级决策与默认倾向

评审一个 PR 并提交 review 时，指南要求你在四种动作中有意识地选择，而不是随手点按钮：

动作	适用场景
✅ Approve	PR 现状良好，可直接合并
✅ Approve with comments	有几个问题需要作者解答/处理，处理完即可合并
🗣️ Comment	你还没把握给出 approve，但希望别人先审、自己只提问
🚫 Request changes	最后手段（a last resort）

围绕这四种动作，指南给出了一系列关键细则：

• Approve with comments 的信任原则：提交后请相信其他维护者不会在评论被处理前合并该 PR，不需要让作者再干等 24 小时换一轮 review。如果开启了 auto-merge 也无需担心——PR 上的评论必须先被手动 resolve 才会触发自动合并，因此即使别人刚留了评论，你依然可以正常 approve。
• Request changes 的两种语境：
  • 评审非维护者的 PR 时，语义是“这些改动在任何人合并之前必须完成”；改动完成后，其他维护者可以 dismiss 这条 review。
  • 评审其他维护者的 PR 时，应尽量避免使用；留给一种情形：“如果这个 PR 在我本人有机会 approve 之前被合并了，它很可能造成用户可见的问题”。
  • 项目负责人（Project Leader）可以用它表达“这个功能本身在 Homebrew 中不可接受”；此时应暂停进一步代码改动，先就该功能是否可接受达成共识。

与动作选择配套的评审文化同样重要，原文的“Relatedly”清单可以概括为八条：

1. 默认选项应该是 ✅ approve（可带评论）；
2. 维护者能做的最有价值的事，是解除另一位维护者工作的阻塞；
3. 尽可能使用 GitHub 的 suggestion 功能直接给出你期望的代码改法；实在只有几分钟时间时，快速扫一眼并留 suggestion 也远好于让 PR 一直无人评审；
4. 团队是全球分布的，这种轻量协作让整体节奏更快；
5. PR 评审本质上是一种安全措施，而不是要在合并前抓住所有 bug 的手段。它要回答的问题是：这个 PR 是否大体做了它声称要做的事？是否避免了削弱沙箱或其他安全边界之类的无关、令人意外的变更？评审当然也能提升代码质量、帮助维护者互相学习，但一个已经就绪的 PR，通常合并后再迭代比等待一个永远不来的“完美评审”更好——评审是有用的护栏，不是绝对的技术屏障；
6. 维护者任期越长，评审时应假定其能力越高；
7. 评审或创建 AI 辅助贡献时，必须遵循 Responsible AI Usage：你对自己提交的输出负责，且在请别人评审之前必须先自己评审过；
8. 工程上，approve 之后随时可以再改（后续 PR 处理评论、或打 tag 前 revert）；而没有 approve 的 PR（几乎）不可能被合并——所以“该松则松”并不增加风险。

指南还给了一个实用的操作技巧：用 gh pr checkout <URL>（GitHub CLI）可以把任意 PR 的分支直接 checkout 到本地，是本地验证改动最省事的入口。

4. 合并门槛：一次 approve + 全绿 CI

brew 维护者指南（docs/Homebrew-brew-Maintainer-Guide.md）把上述评审规范落成了两条硬性合并条件：

• 至少一名维护者 approve；
• CI 全部通过——这是强制步骤，CI 失败的 PR 永远不应合并。

合并方式也有讲究：Homebrew/brew 使用标准的 “Merge” 按钮合并，以保留原始历史与 GPG 提交签名，“Squash and Merge” 与 “Rebase and Merge” 按钮在仓库中已被禁用；如可能，PR 的提交应带有签名。

每个 PR 都会触发一整套 CI 检查（按变更文件不同，包括类型签名、风格、macOS/Linux 上的单元与集成测试、formula 与 cask 审计、vendored 依赖校验、文档构建、Docker 镜像打包测试等），Codecov 则单独汇报测试覆盖率。指南建议把 Codecov 当作“哪里可能需要补测试”的指引，而不是不可逾越的门槛。

5. 源码剖析：自动批准过期 lead maintainer PR 的流水线

指南中“Homebrew/brew has a narrow automatic approval workflow”一句背后，是一条真实运行的 GitHub Actions 流水线。它是本文最重要的“规则如何变成代码”的案例。

5.1 触发方式

工作流定义在 .github/workflows/approve-stale-lead-maintainer-prs.yml：

• 定时触发：cron: "17 0,6,12,18 * * 1-5"，即工作日的 0/6/12/18 时（UTC）各跑一次，间隔六小时扫描一遍过期的 lead maintainer PR；周末不运行，若 48 小时窗口恰好在周末到期，实际批准会顺延到周一（见 docs/Homebrew-brew-Maintainer-Guide.md 的说明）；
• 手动触发：workflow_dispatch 并传入具体 pull_request 编号，可用于对单个 PR 做“干跑”验证——不满足条件时会以 ::error:: 逐条打印失败原因并退出码 1；
• 权限最小化：仅申请 pull-requests: write 与只读的 checks/contents/issues/statuses，且 if: github.repository == 'Homebrew/brew' 防止被 fork 复用。

5.2 十项判定条件

核心逻辑在 .github/scripts/approve_stale_lead_maintainer_prs.rb 的 StaleLeadMaintainerPrApproval 类中。常量定义（第 15–24 行）已经揭示了规则边界：

REPOSITORY = "Homebrew/brew"
APPROVABLE_CHECK_RUN_CONCLUSIONS = ["success", "neutral", "skipped"].freeze
HUMAN_REVIEW_WINDOW_HOURS = 48
SENSITIVE_PATH_PREFIXES = [".github/"].freeze
SENSITIVE_PATHS = [
  "Library/Homebrew/utils/github.rb",
  "README.md",
].freeze

finish 方法（第 369–380 行）把这些条件合成为最终判定：只有全部满足且 bot 尚未对当前 commit 批准过，should_approve 才为真。逐条对照文档表述：

1. 不是 fork 来源：head.repo.full_name == @repository 且 head.repo.fork == false（第 194–195 行）；
2. 不是 draft；
3. 工作日的批准窗口：@weekday_approval_window = (1..5).cover?(Time.now.utc.wday)（第 98 行），周六日直接跳过；
4. 作者是 lead maintainer：名单不是硬编码在脚本里，而是运行时从 README.md 中 “Homebrew's [Lead Maintainers]” 一行用正则抓取 GitHub 用户名（第 81–90 行）——人员名单变动时只需改 README，脚本自动跟随；
5. 作者近 7 天内批准过另一个 Homebrew/brew PR：通过 GitHub Search API 以 reviewed-by:<author> review:approved 分页检索（第 261 行），用来证明该维护者近期有真实评审活动；该前置批准可以来自 fork 上的 PR，因为它只是“近期维护者活动”的证据；
6. PR 已打开至少 48 小时：HUMAN_REVIEW_WINDOW_HOURS = 48，即给其他维护者留出人工评审窗口；
7. 创建以来没有任何人工 review：脚本遍历 reviews，剔除 user.type == "Bot" 的记录后要求列表为空（第 293–304 行）；
8. Copilot 已评审过：存在 type == "Bot" 且 login 含 copilot 的 review（第 305–309 行）——用机器评审垫底，人类评审缺位时才放行；
9. 未触碰敏感路径：变更文件不得命中 .github/ 前缀，也不得是 Library/Homebrew/utils/github.rb（GitHub 交互核心）或 README.md（lead maintainer 名单来源，改它等于改规则本身）；
10. 所有 CI 通过（含非必需项）：遍历 head commit 的 check-runs，status == "completed" 且结论在 success/neutral/skipped 之内才算通过，同时要求 commit status 全部为 success（第 337–363 行）。

满足后，脚本向 GitHub API 的 pulls/{n}/reviews 端点提交 event: "APPROVE"，正文是一段结构化的 Markdown，逐条列出本次自动批准所依据的全部事实并附对应链接（PR 地址、checks 页、作者主页、README 等）——自动化审批本身也遵循了“决策必须可追溯、可被链接”的项目沟通准则。脚本最后还会把每个 PR 的完整判定事实写入 GITHUB_STEP_SUMMARY，让任何人在 Actions 页面都能审计这次批准。

5.3 值得借鉴的工程细节

• 报告分支：push 到 approve-stale-lead-maintainer-prs 分支时走 report 路径，只“打印”某个 PR 是否会获批而不下手，为规则调整提供了安全的试验通道；
• 逐条短路 + 失败信息：evaluate 按代价从低到高检查（fork/draft 最先，CI 最后），failures_for 负责把每个未满足条件翻译成人话，人工与自动路径共用同一套事实结构 PullRequestFacts；
• 幂等：already_approved 检查 bot 是否已对同一 commit_id 批准过，避免重复 approve。

6. 常见“gotchas”：提交侧的三个坑与三条纪律

指南把“Common gotchas”压缩得很短，但每一条都对应一类真实事故：

1. 先确认 git 用户名与邮箱配置正确（git config user.name / git config user.email），否则贡献者归属与通知会错乱；
2. 如果你 amend 过 cherry-pick，必须补 sign-off：git commit --amend --signoff，保证 DCO 签名链完整；
3. 修 bug 的提交使用 issue 链接语法（如 Fixes #104），让 issue 自动关闭并建立 issue 与 commit 之间的双向链接。

其后是三条更偏文化但同样刚性的纪律：

6.1 加注释（Add comments）

引用一个 issue 编号有时就够了，但必须保证改动和上下文对第一次读它的人自明——“你不想自己写的代码因为某个新维护者看不懂为什么而存在，最后被删掉。回归是令人沮丧的。”这条同样适用于 issue 与 PR 正文：尽量显式；如果 PR 是某个大计划的一部分，链接到 tracking issue；没有 tracking issue 就先创建一个，用于沟通与达成共识。

6.2 不允许臃肿的 diff（Don’t allow bloated diffs）

• cherry-pick 时 amend 掉那些只包含空白变更的提交：Homebrew/brew 的历史很重要，git blame 必须保持有用；
• 唯一的例外：某行本身已有实质性修改时，允许顺手把该行的空白改成符合 Ruby 风格的写法；
• 修改**内嵌 patch（inline patch）**时要格外小心，确保 patch 依然能应用。

6.3 关闭 issue/PR 的边界（Closing issues/PRs）

• 维护者（包括项目负责人）不应关闭其他维护者打开的 issue 或 PR——除非它已 stale，stale 的可以由任何维护者关闭；注意“合并”不算“关闭”；
• 任何维护者被鼓励重开已关闭的 issue 以便继续推进工作；
• 反过来，任何维护者都可以合并自己认真评审过且 CI 全绿的、由其他维护者打开的 PR；如果你不希望别人合并你的 PR，就用 draft 状态表明它还没准备好。

7. Revert：一小时的自愈窗口

指南对回滚的授权写得非常具体：任何维护者可以在“某个用户提交了 issue”或“CI 失败”之后，revert 另一位维护者创建的 PR；但原作者应被给予不少于一小时的时间，由他自己修复问题、或自己决定 revert。

这条规则与 Maintainers-Avoiding-Burnout 第 5 节的“慢下来”互为表里：与其焦虑地追求一次做对，不如相信“现在先 revert，明天再给正式修复”总是可行路径。指南也呼应了第 3 节的评审文化：批准之后改、发 tag 之前 revert，成本都很低。

8. 24 小时规则：给其他维护者留出评审窗口

这是原文中最容易量化的一条流程规则。凡是对既有功能的增强型 PR——即不属于以下四类的：

• 未解决的用户 issue/discussion 的修复；
• 版本号 bump；
• 安全修复；
• CI 失败修复；

而属于可用性改进、新功能、重构等“enhancement”的，应在周一至周五提交后等待 24 小时再合并。原文给出三个可直接照搬的例子：

• 周四 17:00 提交的新功能 PR → 最早周五 17:00 合并；
• 周五 17:00 提交的可用性改进 PR → 最早周一 17:00 合并（跨周末）；
• 用户上报问题的修复 PR：CI 变绿后可以立即合并，不受 24 小时约束。

两条配套约定：

• 如果某位维护者在此期间休假/病假，回来后才留的评论，应当作在窗口期内留的一样对待：同意其诉求时，用后续 PR 去解决；
• Homebrew/homebrew-core 中绝大多数 PR 是 bug 修复或版本 bump，CI 完成后即可自行合并——所以 24 小时规则的实际影响范围比字面上小得多。

这条规则与第 5 节的自动批准流水线形成对照：前者用时间缓冲保护“人”的评审机会，后者用确定性规则把确实无人评审的非敏感 PR 安全放行，两者共同维护“有 approve 才能合并”这条底线。

9. 沟通规范：公共优先，决策必须可被链接

指南对维护者之间的沟通划定了三个层级与一条铁律：

1. 首选：GitHub 上的公共仓库——理想情况下所有沟通都应公开发生；
2. 次选：维护者私有群组（如 GitHub/Slack 的多人频道），适用于安全披露、紧急破坏需要快速处置等不宜公开的场景；
3. 再次：两人之间的 1:1 私聊（iMessage/Slack/“信鸽”亦可）。

铁律是：技术决策不应发生在 1:1 沟通中；如果已经（或曾经）发生了，最终必须回到 GitHub 变成可链接的内容。原文给了一个生动的场景：一年前在 Slack 上做出的技术决策，当有维护者/贡献者/用户在 GitHub 上问起时，正是解释它、让它获得可引用 URL 的好时机。这样做的收益是双重的——其他人能跟上“我们在做什么，以及为什么”，且每个决策都有一个可链接的地址。

其余要点：

• 当上游开发者或代表加入讨论时，注意他们可能默认的是“有长期负责该包的维护者”的发行模式。保持讨论在 GitHub 公开进行，适时把对方引向 Working with Homebrew as an Upstream Project，并建议把格局更大的关切挪到 issue 里讨论；
• 所有维护者（含项目负责人）在任何媒介上的言行都受 Homebrew 行为准则（Code of Conduct）约束：对维护者、贡献者或用户的侮辱性行为不被容忍，会先警告、持续则移除其维护者身份；
• 维护者之间可以且被鼓励对彼此的工作与决策提出礼貌的技术分歧——健康的分歧应发生在公共 issue tracker 上；人际问题则私下（Slack，最好有调解人）处理。对文档或解释不足的工作，任何人都有权要求澄清；
• 没有维护者可以仅以“因为我说了算”或“当初 X 是我做的”来为自己的决策辩护；
• issue tracker 上的跑题讨论、无意义的纠结（bike-shedding）与人身攻击被明令禁止。

10. 小结：把规范写成规则，把规则写成代码

回看 docs/Maintainer-Guidelines.md 的完整脉络，Homebrew 的维护者体系可以概括为三层递进：

1. 决策分级：四种 review 动作各有语义，approve 是默认，request changes 是最后手段；评审是安全护栏而非完美主义关卡；
2. 流程缓冲：24 小时增强型 PR 窗口、Revert 前的一小时自愈期、stale 才能关闭他人 issue——用时间窗口代替即时冲突；
3. 机器执行：当“无人评审的非敏感 PR”这一场景被精确刻画后，.github/ 下的一条 Actions 流水线就能以十项可审计的条件安全地代替人工 approve，且名单、窗口、敏感路径都以常量与 README 为唯一事实来源。

配套文档可按需深入：Homebrew/brew Maintainer Guide（合并与 CI 细节）、Maintainers: Avoiding Burnout（倦怠防范五原则）、Responsible AI Usage（AI 辅助贡献的评审责任）、Working with Homebrew as an Upstream Project（面向上游开发者的协作模式），以及仓库根的 AGENTS.md（提交前必须跑 ./bin/brew lgtm 等具体开发约定）。