Homebrew/homebrew-core 维护者指南

快速合并清单

可以在 下方 找到详细清单。这些是真正重要的内容

检查依赖项很重要，因为它们可能永远存在。没有人真正检查它们是否必要。

尽可能少地依赖东西。如果可能，禁用 X11 功能。例如，我们构建 Wireshark，但不构建繁重的 GUI。

Homebrew 是关于 Unix 软件的。构建到 .app 的内容应该在 Homebrew Cask 中。

合并、重新设定基础、挑选

对于大多数对公式进行修改的 PR，你可以简单地批准 PR，@BrewTestBot 将执行自动合并（带容器）。有关更多信息，请参阅 BrewTestBot for Maintainers。

某些 PR 可能不会被 @BrewTestBot 自动合并，即使它们已被批准。这包括带有 new formula 和 automerge-skip 标签的 PR。要触发这些 PR 的合并，请运行 brew pr-publish。

修改不需要容器的公式或进行不需要拉取新容器的更改的 PR 应使用 GitHub 的合并和合并或重新设定基础和合并工作流。

否则，你应该使用 brew pr-pull（或 rebase/cherry-pick 贡献）。

不要在最终 push 之前 rebase。一旦 master 被 push，你就不能 rebase：你现在是维护者了！

选择更改会改变提交日期，这有点糟糕。

不要合并不干净的分支。因此，如果有人仍在学习git，并且他们的分支充满了无意义的合并，那么重新设定基础并压缩提交。我们的主分支历史应该对其他人有用，而不是令人困惑。

只需要一个维护人员批准并合并通过 CI 的新公式或更新公式的添加。但是，如果公式添加或更新被证明有争议，添加它的维护人员将被期望回答请求并解决将来出现的问题。

如何在没有容器的情况下合并

以下是有关何时使用压缩和合并与重新设定基础和合并的指南。这些选项仅应与未受容器影响的 PR 一起使用。

  PR 修改单个公式 PR 修改多个公式
提交看起来不错 重新设定基础和合并或压缩和合并 重新设定基础和合并
提交需要修改 压缩和合并 使用命令行手动合并

命名

名称是最严格的项目，因为避免以后更改名称是可取的。

选择一个作为项目最常用名称的名称。例如，我们最初选择了objective-caml，但我们应该选择ocaml。选择人们在谈论该项目时互相说的话。

由其他包管理器（例如 Debian、Ubuntu）打包的公式应始终如一地命名（受 Homebrew 公式命名约定的细微差异影响）。

使用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）有大量的依赖项。这使得更新这些公式（或其依赖项）变得困难，因为标准程序涉及在单个拉取请求中更新大量公式。一种可以极大地简化此过程的替代程序是使用暂存分支。

使用暂存分支的想法是将更新合并并为受影响的公式发布瓶子到非默认分支。这允许以较小的 PR 逐步完成工作，而不是在一个涉及许多公式的巨大 PR 中。当暂存分支准备就绪时，可以将其合并到 master/默认分支。

在使用暂存分支之前，有一点重要的缺点需要考虑：一旦将瓶子更新合并到暂存分支，就非常困难将它们取回。这通常涉及删除上传的瓶子，有时需要 Homebrew GitHub 组织的所有者逐个删除上传的瓶子。

如何使用暂存分支

以下是如何使用暂存分支的大致概述

  1. 在 Homebrew/homebrew-core 中创建暂存分支。暂存分支的名称必须以根公式的名称开头，后跟 -，并以 -staging 结尾。对于版本化公式，你可以省略 @ 及其后的任何内容（例如 icu4c-staging、openssl-migration-staging、[email protected]）。查看 代码 可能会很有帮助，该代码解析分支名称以检查 PR 是否针对暂存分支。

  2. 在 homebrew-core 中打开一个问题，邀请贡献者提供帮助。务必包含有关如何执行此操作的说明，以及需要更新的公式清单。有关示例，请参见 Homebrew/homebrew-core#134251。

  3. 打开一个草稿 PR，将暂存分支合并到 master 分支。这允许你跟踪迄今为止所做的工作。你可能希望将 no long build conflict 标签应用于此 PR，以避免将冲突更改合并到 master 分支。

  4. 开启针对 staging 分支的 PR，更新受影响的公式。每个 PR 应尽可能少地涉及公式。针对 staging 分支的典型 PR 一次只更新一个公式。Staging 分支 PR 可使用与针对 master 分支的 PR 相同的过程进行合并。理想情况下，这些 PR 应根据依赖关系图以 拓扑顺序 在中开启，但我们目前没有用于生成拓扑排序的良好工具。（欢迎提供帮助。）

  5. 使用 staging-branch-pr 标签标记针对 staging 分支的 PR，以便于跟踪和审查。（待办事项：为 homebrew-core 添加一些自动化功能。）

  6. 监视在步骤 3 中创建的草稿 PR 是否存在合并冲突。如果您遇到合并冲突，您必须在 staging 分支 PR 中解决这些冲突，该 PR 将 master 分支合并到 staging 分支中。

  7. 当 staging 分支准备好合并到 master 中时，将草稿 PR 标记为准备审查，并将其合并到 master 分支中。您的 PR 可能会在合并队列中花费很长时间，等待瓶子获取测试运行。

有关 staging 分支使用示例，请参阅标记为 openssl-3-migration-staging、Homebrew/homebrew-core#134260 或 Homebrew/homebrew-core#133611 的 homebrew-core PR。

最后：虽然在使用过的两个实例中，使用 staging 分支非常有效（请参阅上一段中链接的 PR），但上述过程并不完美。非常欢迎提出改进建议。

Fork me on GitHub