Homebrew 文档

维护者指南

本指南适用于维护者。这些特殊人员拥有 Homebrew 存储库的写入权限，并帮助合并他人的贡献。您可能会发现这里写的内容很有趣，但它绝对不是初学者指南。

您可能正在寻找 配方手册 或 Cask 手册？

概述

鼓励所有 Homebrew 维护者为项目的各个部分做出贡献，但维护者往往属于四个主要团队

• brew 维护者：此团队维护 Homebrew/brew 存储库。有关成为 brew 维护者的更多详细信息，请参阅 Homebrew/brew 维护者指南。
• 核心维护者：此团队维护 Homebrew/homebrew-core 存储库。有关成为核心维护者的更多详细信息，请参阅 Homebrew/homebrew-core 维护者指南。
• Linux 维护者：此团队在 Linux 上维护 Homebrew/homebrew-core 存储库。
• Cask 维护者：此团队维护 Homebrew/homebrew-cask 和 Homebrew/homebrew-cask-fonts 存储库。有关成为 Cask 维护者的更多详细信息，请参阅 Homebrew/homebrew-cask 维护者指南。

这些文件旨在作为指导原则。作为一名维护者，您可以根据贡献者的舒适度和以往贡献，要求他们更改或帮助他们。请记住，作为一个团队，我们 优先考虑维护者而非用户 以避免倦怠。如果您希望更改或讨论任何指南：请打开 PR 以建议更改。

审阅 PR

在审阅 PR 时，根据以下指南提交时使用“批准”、“带评论批准”、“评论”或“请求更改”

• ✅ 批准：如果您觉得 PR 看起来不错，您可以按原样 ✅ 批准它。
• ✅ 带评论批准：如果您有一些问题或评论需要回答，并且 PR 在解决这些问题后可以合并，您可以 ✅ 带评论批准。
  • 请相信其他维护者不会在解决评论之前合并 PR，而不是让他们再等 24 小时以获得另一条审阅。
  • 如果启用了自动合并：如果你想要确保在你的评论至少被阅读之前 PR 不会被合并，你可以禁用它（在 homebrew-core/cask 中添加 automerge-skip）。
• 🗣️ 评论：如果你需要在提供 ✅ 批准之前提出问题，但对于其他人在你之前提供 ✅ 批准没有意见，请提供评论审查并提出问题。
• 🚫 请求更改：最后的手段。
  • 在审查非维护者的 PR 时：这意味着“在任何人合并此 PR 之前必须进行这些更改”。其他维护者可以在这些更改完成后驳回此审查。
  • 在审查其他维护者的 PR 时：只要有可能，都应避免这样做。
    • 将其保存为“如果此 PR 在我个人有机会 ✅ 批准之前被合并：它似乎很可能导致用户可见的问题”。
    • 项目负责人可能会将其用于“此功能在 Homebrew 中不可接受”。在这种情况下：应推迟其他代码更改，直到同意该功能可接受为止。

相关

• 默认选项应该是 ✅ 批准，无论是否有评论。
• 只要有可能，你都应该尝试使用 GitHub 的“建议”功能来编辑代码，使其符合你的要求。如果你没有时间或不想费心：你可能没有时间正确审查 PR。
• 我们是一个全球分布的团队，这有助于我们更快地行动。
• PR 审查流程主要是一种安全措施，而不是在合并之前就完美的代码风格达成共识的方法。
• 在批准后很容易对 PR 进行更改，进行后续 PR 以解决评论或在标记之前还原 PR。
• 在未经批准的情况下合并 PR 是（几乎）不可能的。
• 使用 gh pr checkout <URL> 是使用 GitHub CLI 签出 PR 分支的超简单方法。

使命

Homebrew 旨在成为 macOS（和 Linux）的缺失包管理器。它的主要目标是尽可能对尽可能多的人有用，同时由一小群志愿者以专业、高标准的方式维护。在可能和合理的情况下，它应该寻求使用 macOS 的功能来融入 macOS 和 Apple 生态系统。在 Linux 和 Windows 上，它应该尽可能自包含。

常见的“陷阱”

1. 确保你已正确设置用户名和电子邮件地址
2. 如果你修改了樱桃选取，请签出（使用 git -s）
3. 如果你的提交修复了一个错误，请使用问题链接语法（例如“修复 #104”）来关闭错误报告并链接回提交

添加注释

仅仅引用一个问题单可能就足够了，但请确保更改和上下文足够清晰，以便任何首次阅读它们的人都能理解它们。你不想让别人删除你编写的代码，因为新来的人不理解它为什么在那里。回归很糟糕。

这也适用于问题和 PR 正文。尽可能明确。如果一个 pull 请求是更大举措的一部分：链接到相关的跟踪问题。如果还没有跟踪问题：创建一个以改善沟通并达成共识。

不允许臃肿的差异

修改 cherry-pick 以删除仅在空白处更改的提交。它们不可接受，因为我们的历史很重要，并且git blame 应该有用。

允许空白更正（例如，针对 Ruby 标准等）（事实上，这是一个很好的机会），前提是该行本身有一些不仅仅是空白更改的修改。但要小心对内联补丁进行更改——确保它们仍然适用。

关闭问题/PR

维护人员（包括项目负责人）不应关闭由其他维护人员打开的问题或 pull 请求（请注意，在这种情况下，合并不被视为关闭），除非它们已过时，在这种情况下，任何维护人员都可以关闭它们。鼓励任何维护人员在希望对问题进行额外处理时重新打开已关闭的问题。

任何维护人员都可以合并他们仔细审查过的任何 PR，并且该 PR 已通过由任何其他维护人员打开的 CI。如果你不希望其他维护人员合并你的 PR：请使用草稿 pull 请求状态来表明，直到你准备自己合并它为止。

还原 PR

在用户提交问题或 CI 失败导致问题后，任何维护人员都可以还原由另一个维护人员创建的 PR。创建原始 PR 的维护人员应获得不少于一小时的时间来自己修复问题或决定自己还原 PR（如果他们愿意）。

给其他维护人员时间进行审查

对现有功能进行“增强”的 PR，即不是对开放用户问题/讨论的修复，不是版本升级，不是安全修复，不是对 CI 失败的修复，可用性改进，新功能，重构等。应该在周一至周五的 24 小时内合并。例如，

• 周四下午 5 点提交的新功能 PR 应该等到周五下午 5 点才能合并
• 在周五下午 5 点提交的可用性修复 PR 应等到周一下午 5 点再合并
• 用户报告的问题修复 PR 可以在 CI 变为绿色后立即合并

如果维护者在此期间休假/度假/生病并在返回后留下评论：请将合并后 PR 评论和反馈视为在时间段内留下的评论，并通过另一个 PR 来跟进他们的请求（如果同意）。

绝大多数 Homebrew/homebrew-core PR 是错误修复或版本升级，可以在 CI 完成后进行自我合并。

沟通

维护者有多种方式相互沟通

• GitHub 上 Homebrew 的公共存储库
• Homebrew 在私人频道（例如 GitHub/Slack）上两个以上维护者之间的群组通信
• Homebrew 在私人频道（例如 iMessage/Slack/信鸽）上两个维护者之间的直接 1:1 消息

所有通信最好在 GitHub 上公开进行。如果不可能或不合适（例如安全披露、两个维护者之间的人际问题、需要解决的紧急中断），则可以转移到维护者的私人群组通信，必要时可以进行 1:1 通信。技术决策不应在 1:1 通信中发生，但如果发生（或过去发生），则必须最终返回到 GitHub 上可链接的内容。例如，如果一年前在 Slack 上做出了技术决策，并且另一位维护者/贡献者/用户在 GitHub 上询问它，这是一个很好的机会向他们解释它并提供将来可以链接到的内容。

这使得其他维护者、贡献者和用户更容易了解我们在做什么（更重要的是，了解我们为什么这样做），并且意味着决策有一个可链接的 URL。

所有维护者（和项目负责人）通过任何媒介进行的通信都受 Homebrew 的行为准则 约束。对其他维护者、贡献者或用户的虐待行为将不被容忍；维护者将收到警告，如果他们的行为继续，他们将被移除为维护者。

维护者应该随时对其他维护者的工作和决策提出异议。积极鼓励维护者之间进行健康、友好的技术分歧，并且应该在问题跟踪器上公开进行，以使项目变得更好。人际问题应在 Slack 上私下处理，最好由主持人主持。如果工作或决策没有得到充分的记录或解释，任何维护者或贡献者都可以随时要求澄清。没有哪个维护者可以仅仅用“因为我说过”或“是我做了 X”来证明一个决定。禁止在问题跟踪器上进行无关讨论、吹毛求疵和人身攻击。