Homebrew Autobump 机制解析：官方仓库的自动版本升级与 no_autobump! 排除策略

Homebrew 的 Autobump 机制让官方仓库（Homebrew/core、Homebrew/cask）中的软件包无需贡献者手动提交升级 PR：由 BrewTestBot 驱动的 GitHub Action 每 3 小时扫描一次 autobump 列表中的软件包，发现新版本后自动开启升级 Pull Request。本文基于仓库文档 docs/Autobump.md 及核心实现源码，完整讲解该机制的运作方式、三种排除条件、no_autobump! 的合法参数取值，以及 RuboCop 对排除理由的静态审计规则，帮助你在维护官方 tap 中的软件包时正确配置自动升级行为。

Autobump 的工作方式

在官方仓库中，BrewTestBot 会自动检查处于 Homebrew "autobump 列表" 中的软件包是否有可用更新。这些软件包不需要贡献者手动 bump（即手动提升版本号）：每隔 3 小时，一个 GitHub Action 会检查是否需要升级，并在需要时自动开启一个新的 Pull Request 将其升级到最新版本。

这意味着对于处于 autobump 列表中的包，维护者只需保证 formula/cask 定义正确，版本迭代由 CI 流水线负责。列表的默认覆盖范围非常宽：

默认情况下，Homebrew/core 和 Homebrew/cask 仓库中所有新增的 formula 和 cask 都会进入 autobump 列表。

因此，"如何把某个包排除出去"比"如何加入"更有实际意义。

将软件包排除出 autobump 的三种方式

要让一个软件包不进入 autobump 列表，它必须满足以下其中任意一个条件：

1. 存在生效的 deprecate! 或 disable! 调用 —— 已被废弃或禁用的包不会再被升级；

2. livecheck do 块中包含 skip 调用 —— livecheck 被显式跳过，例如：

   livecheck do
     skip "Not maintained"
     url "https://example.com/foo/releases"
     regex /foo-(\d+(?:\.\d+)+)\.tar/
   end
   

   该 DSL 形式对应源码中 formula.rb 的 livecheck 方法，它在 Livecheck 对象的上下文中执行块内容，skip 即向自动检查流水线声明"该包不做版本检查"。livecheck 的更多用法见 Brew-Livecheck.md。

3. 存在 no_autobump! 调用 —— 主动声明排除并给出理由，详见下一节。

此外，formula 与 cask 各自还有若干特定的不自动升级原因，分别列于 Formula Cookbook（"Excluding formulae from autobumping" 小节）与 Cask Cookbook 中。

值得注意的是，除了上述显式声明，还有两种隐式排除由 DSL 自动完成，见源码 cask/dsl.rb：

• cask 的 version 设置为 :latest 时，会自动以 :latest_version 为由调用 set_no_autobump；
• cask 的 livecheck 策略为 :extract_plist 时，会自动以 :extract_plist 为由排除（cask/dsl.rb）。

这两种情况不需要（也不应该）手写 no_autobump!，理由本身由系统自动填入。

no_autobump! 排除理由：符号优先、字符串兜底

使用 no_autobump! 时必须提供排除理由。有两种书写方式：

方式一（推荐）：使用预置符号。 合法符号定义在常量 NO_AUTOBUMP_REASONS_LIST 中（源码见 autobump_constants.rb）：

no_autobump! because: :bumped_by_upstream

方式二：自定义字符串。 当预置理由都不适用时，可以直接写字符串：

no_autobump! because: "some unique reason"

文档同时指出：如果多个软件包有相似的自定义理由，可以将其作为新符号加入 NO_AUTOBUMP_REASONS_LIST，实现理由复用。

常量中的全部合法理由

从 Library/Homebrew/autobump_constants.rb 的源码可以看到，NO_AUTOBUMP_REASONS_LIST 由三部分合并而成，共 5 个符号：

符号	含义	来源
:incompatible_version_format	包的版本格式只能人工更新	公开理由（NO_AUTOBUMP_REASONS_LIST 直接定义）
:bumped_by_upstream	包的更新由上游开发者负责处理	公开理由
:extract_plist	livecheck 使用了 :extract_plist 策略	内部理由（NO_AUTOBUMP_REASONS_INTERNAL，由系统自动设置）
:latest_version	version 被设置为 :latest	内部理由（NO_AUTOBUMP_REASONS_INTERNAL，由系统自动设置）
:requires_manual_review	该包的 autobump 纳入需要人工审查	已废弃理由（NO_AUTOBUMP_REASONS_DEPRECATED）

可以看到源码把符号分为公开、内部、废弃三档，这一分档直接约束了维护者的使用方式——内部与废弃符号有各自的校验逻辑（下文 RuboCop 审计一节详述）。

参数校验：官方 tap 限制与符号合法性

no_autobump! 的实现位于 formula.rb（formula 侧）与 cask/dsl.rb（cask 侧），两者行为一致：

def no_autobump!(because:)
  caller_path = caller_locations(1, 1)&.first&.path
  if caller_path
    tap = Tap.from_path(caller_path)
    raise ArgumentError, "no_autobump! can only be used in official Homebrew taps." if tap && !tap.official?
  end

  if because.is_a?(Symbol) && !NO_AUTOBUMP_REASONS_LIST.key?(because)
    raise ArgumentError, "'because' argument should use valid symbol or a string!"
  end
  # ...
end

由此可以确认三条硬性约束：

• 只能在官方 tap 中使用：从调用者文件路径解析出所属 tap，若非官方 tap 则抛出 ArgumentError（cask 侧抛出 CaskInvalidError）。第三方 tap 无法使用该 DSL 语句；
• 符号必须合法：传入 Symbol 时会查 NO_AUTOBUMP_REASONS_LIST，不在表中的符号直接报错；字符串则不做白名单校验；
• cask 中该语句只能出现一次：cask/dsl.rb 的 set_no_autobump 在 no_autobump_defined? 已为真时再次调用会抛出 "'no_autobump!' stanza may only appear once." 错误（formula 侧则通过 @autobump 状态位生效）。

调用成功后，软件包的 @autobump 被置为 false，autobump? 返回 false，排除理由存入 no_autobump_message。这两个属性还会随官方 API 一起对外暴露——见 formula.rb 中 "autobump" => autobump?、"no_autobump_message" => no_autobump_message 的 API 序列化映射，下游工具可以据此判断一个包是否处于自动升级列表。

对于非官方 tap，仓库采用另一种管理方式：tap_auditor.rb 检查第三方 tap 的 .github/autobump.txt 文件与其声明的 autobump 列表是否一致，即第三方 tap 通过维护一份文本清单来表达升级策略，而不是依赖 no_autobump!。

RuboCop 静态审计：理由字符串的书写规范

排除理由不仅要"存在"，还要"写得规范"。仓库为 formula 和 cask 各配了一个 RuboCop 审计 cop——rubocops/no_autobump.rb 与 rubocops/cask/no_autobump.rb——共用 rubocops/shared/no_autobump_helper.rb 中的规则模块，对应测试见 test/rubocops/no_autobump.rb。其规则包括：

1. because: 参数不可缺失：若 no_autobump! 没有 because: 字符串或符号参数，直接报告 Add a reason for exclusion from autobump: 'no_autobump! because: "..."'；
2. 禁止使用内部自动理由符号：:extract_plist 与 :latest_version 属于系统内部自动设置（见上文的 DISALLOWED_NO_AUTOBUMP_REASONS 列表），人工写入会被判为错误——这两个场景应由 version :latest 或 :extract_plist 策略自动触发，而非手写；
3. 字符串理由不能以 it 开头（支持 autocorrect 自动去掉前缀）；
4. 字符串理由不能以标点符号（. ! ?）结尾（同样支持 autocorrect 自动删除末尾标点）。

这些规则说明理由字符串会被集中展示给维护者与 CI 系统，因此仓库要求它像常量说明一样是"陈述性短语"而非完整句子。

小结：配置时的决策路径

结合文档与源码，为官方 tap 中的软件包配置 Autobump 行为时的判断顺序为：

1. 包已废弃/禁用（deprecate!/disable!）或 livecheck 被 skip ？——是则已被排除，无需额外声明；
2. cask 使用 version :latest 或 :extract_plist 策略？——系统自动排除，勿手写 no_autobump!；
3. 需要手动排除？——使用 no_autobump!，优先从 NO_AUTOBUMP_REASONS_LIST（见 Library/Homebrew/autobump_constants.rb）选取预置符号（如 :bumped_by_upstream、:incompatible_version_format）；不匹配时用不重复 it 开头、不带末尾标点的短字符串，并且若多个包共享同一理由，考虑将其提升为新符号加入该常量列表。

以上即 Autobump 文档 所述机制的完整实现链路：默认全量自动升级 → 三类显式排除条件 → no_autobump! 的理由约束（DSL 校验 + RuboCop 静态审计 + API 对外暴露）。