Angular Caretaker 指南：掌握 ng-dev pr merge 的 PR 合并、TGP 全局预提交与跨仓库同步机制

Caretaker（维护值班人）是 Angular 仓库每周轮换的一个特殊角色，其核心职责是将带有 action: merge 标签的 PR 合并进仓库，并同步到 Google 内部代码库。本文围绕 contributing-docs/caretaking.md 展开，结合仓库中的标签体系文档、分支版本管理文档及源码目录，系统讲解一个 PR 从"评审通过"到"合入 main 并回灌内部仓库"的完整链路，读完你既能作为维护者正确执行合并操作，也能作为 PR 作者理解标签要求与合并门禁，避免提交被工具拒绝。

Caretaker 是谁：一个按周轮换的角色

从仓库的治理文档看，Angular 的日常维护被拆分为若干明确角色，而 caretaker 是其中最靠近"合并按钮"的一环。它的定位非常聚焦：

• 负责合并带有 action: merge 标签的 PR（可理解为"作者已声明可以合入"的 PR）；
• 对没有打任何标签的新 issue 做轻量级分流（light issue triage），更细的组件级分流由各组件负责人完成；
• 该角色每周轮换，避免单一维护者长期承担合并压力，也保证合并口径的持续轮训。

值得强调的是，caretaker 在 issue 层面只负责"粗分流"——这一点在 triage-and-labelling.md 中写得很清楚："caretaker only assigns a component (area: *) label"，即 caretaker 只需为新 issue 确定所属领域标签，后续的详细分类、优先级与处理由组件 owner 接手。

一个 PR 可以被合并的前提：双标签机制

并非所有通过评审的 PR 都能被 caretaker 合并。仓库文档明确了一个硬性前提：

A PR requires the action: merge and a target: * label to be merged.

即必须同时具备一个 action: merge 标签和一个 target: * 标签，二者缺一不可。

action: merge 的含义

根据 triage-and-labelling.md 的定义，action: merge 表示"PR 作者已准备好让 caretaker 在 CI 变绿后自动合入"，即 auto submit when ready 的信号。该标签通常由 PR 作者添加，也由添加者自己移除。在 PR 标签体系中，它对应的是这样一个状态机：

action 标签	语义	谁负责添加 / 移除
action: discuss	需要作者牵头讨论	通常由作者添加并移除
action: review	尚有一个或多个评审待完成（可选，因可从 GitHub 评审界面推导）	团队成员添加；评审者确认最后缺失评审通过后移除
action: cleanup	作者还需继续修改	提出修改意见的评审者添加；作者或评审者确认改完后移除
action: merge	作者已就绪，CI 通过即可自动合入	通常由 PR 作者添加并移除

此外还存在 state: WIP 与 state: blocked 两个状态标签，分别表示"实验性/快速变化中，不宜评审或分流"与"被其他 issue/PR 阻塞，不可合并"。

target: * 决定合并去向

target: * 标签唯一决定这次合入会被合并到哪些分支，且一个 PR 只能挂一个 target 标签。它并不是由 caretaker 决定，而是由 PR 作者与评审者商定（见 branches-and-versioning.md）。核心目标标签如下：

标签	适用场景	落地分支
target: major	任何破坏性变更	main（仅当 main 代表下一个大版本时）
target: minor	任何向后兼容的新功能	main
target: patch	无风险或低风险的 bug 修复、重构、文档改动	main、active patch 分支（如有 active RC 分支也会合入）
target: rc	feature freeze / RC 阶段的关键修复	active RC 分支
target: lts	仍在 LTS 窗口内某版本的严重安全/兼容性修复	LTS 分支（需在 GitHub UI 直接指定具体 LTS 分支）

target: automation（仅 angular-robot 账号使用）与 target: feature（针对 feature 分支的变更）不映射到具体版本，仅约束合入分支。若一个 PR 缺少 target: * 标签，angular 机器人状态检查会将其标记为 pending，工具侧直接拒绝合入。

执行合并：pnpm ng-dev pr merge

当 PR 双标签齐备且所有测试通过后，caretaker 通过 Angular 官方的 ng-dev 工具链执行合并，核心命令是：

pnpm ng-dev pr merge <pr number>

这条命令的可用性在仓库根目录的 package.json 中是有依据的：项目通过 npm scripts 暴露了 "ng-dev": "ng-dev"，因此在仓库内用 pnpm ng-dev ... 即可调用对应的命令式工具。整条命令执行时经历的关键阶段如下：

1. 读取并校验标签：命令会读取该 PR 当前的 action: * 与 target: * 标签。若缺少可合并前提，工具会给出明确报错并中止。
2. 自动验证合并就绪状态：工具自动核实 PR 是否满足合并条件（CI 是否通过、评审是否满足、是否与目标分支冲突等），这一"自动检查-通过即合并"的设计正是 action: merge 标签"auto submit when ready"语义的落地实现。
3. 依据 target 标签完成分支操作：PR 先被合入其 base 分支，再由工具依据 target: * 标签把提交 cherry-pick 到相应分支。例如 target: patch 会同时把变更带到 active patch 分支（如有 active RC 分支也会带上），target: lts 则会扩散到 LTS 窗口内所有仍在支持期内的分支。
4. fixup 提交自动折叠：合并脚本具备把 fixup! <原始提交信息> 提交自动 squash 回对应原始提交的能力（详见 using-fixup-commits.md），所以评审往返中产生的 fixup 提交无需作者手动 rebase 整理。

关于 PR 必须通过相应 code owner 评审这一前提，仓库在 triage-and-labelling.md 中还提醒了一个容易踩的坑："approved"并不等于"可以合并"——评审者可能批准代码但要求一个无需再次评审的小改动（如 rebase），只有 action: merge 标签才真正表示"作者已就绪"。

Primitives 等受保护目录：为什么"禁止混着合并"

仓库文档专门说明了一个容易让人意外的规则：代码库中部分目录存在额外的保护规则，最典型的例子是 //packages/core/primitives（即仓库内的 packages/core/primitives 目录）。

该目录下的代码必须与其它变更分开合并、并单独同步进 Google 内部代码库。如果试图把 primitives 相关改动与其他改动合并在一起提交，合并工具会直接报错。这样做的工程动机在文档中解释得很直白：

This practice makes it significantly easier to rollback or revert changes in the event of a breakage or outage.

把"最容易被广泛复用、一旦出错影响面极大"的底层原语代码隔离成独立的最小变更单元，一旦线上出问题，可以只回滚这一小片提交，而不必连带回滚一批无关改动。这种"可独立回滚的最小单元"思路，值得任何有底层共享代码仓库的项目参考。

requires: TGP：何时需要"全局预提交"

Angular 的大部分 PR 在 Google 内部只会针对一组精选的 Angular 应用测试子集运行。但如果某个改动被判定为有风险、或需要更充分的测试覆盖，就需要打上 requires: TGP 标签：

• 打上该标签后，合并工具会强制要求 Google 内部所有受影响的测试都被完整跑过（即一次 "global presubmit"，缩写 TGP）。
• 一个可选的替代路径：Googler 可以在评审评论中以 TESTED= 开头给出理由，说明为什么该 PR 已得到充分测试，从而让合并工具的检查放行。

requires: TGP 标签并不总是手工添加——文档明确说明，凡改动命中了仓库根目录 .ng-dev/google-sync-config.json 中 separateFilePatterns 所匹配文件的 PR，该标签会被自动加上。

TESTED= 注释的标准写法示例如下：

TESTED=docs only update and does not need a TGP

也就是说，若一个 PR 只改了文档、完全不涉及代码行为，就可以用上述格式声明"纯文档改动无需 TGP"，由工具结合人审放行，避免为纯文档改动付出跑全量内部测试的巨大成本。

触发合并冲突后如何恢复

合并流程并非永远一帆风顺。仓库文档明确了一个实用保障：

The ng-dev pr merge tool will automatically restore to the previous git state when a merge fails.

也就是说当 merge-pr 因冲突等原因失败时，ng-dev 工具会自动把本地 git 状态恢复到合并前的快照，不会留下半合并的脏状态。因此 caretaker 处理失败时无需手工清理，直接解决冲突后重跑 pnpm ng-dev pr merge <pr number> 即可。这也是为什么该命令被设计成"安全可重试"——失败即回滚，重试成本极低。

Caretaker 工作流全景：从标签到回灌

将上文内容串联起来，一次完整的 caretaker 合并流程可以归纳为这样一条流水线：

1. PR 作者完成代码与评审往返后，添加 action: merge 标签；评审者/作者同时商定唯一的 target: * 标签；若改动命中 Google 同步保护路径，机器人自动追加 requires: TGP。
2. 工具侧自动检查：CI 状态、评审满足情况、目标标签合法性、TGP 要求是否满足（必要时结合 TESTED= 评论）等，全部通过后按目标标签执行合入与 cherry-pick。
3. 同步内部仓库：合入的变更随后由同步流程进入 Google 内部代码库；其中 //packages/core/primitives 等受保护目录按规则独立成单、单独同步，保证任何时刻都能对其单独回滚。
4. 失败自愈：若合并因冲突失败，工具自动恢复 git 状态，可安全重试。

作为 PR 作者而非维护者，你需要记住的对应动作是：补全 action: merge 与 target: * 标签、确保通过 code owner 评审、如有风险改动给出充分的测试证据（或等待 Googler 的 TESTED= 说明）。另外，若你的 PR 需要特殊关注（例如作者不是 Googler、需要协助触发 g3sync，或某项检查因外部原因失败但仍应合并），还可以添加 action: merge-assistance 标签，并必须在 PR 评论中以 merge-assistance: <说明需要何种协助及原因> 的格式留言，供 caretaker 决策（详见 triage-and-labelling.md）。

进一步阅读

• contributing-docs/triage-and-labelling.md：issue 粗分流/细分流流程、P0–P5 优先级、全部 action:/state:/target: 标签的完整语义与负责人。
• contributing-docs/branches-and-versioning.md：main / \d+\.\d+\.x 分支命名、大版本发布节奏、各 target: 标签实际落地的分支矩阵。
• contributing-docs/using-fixup-commits.md：评审往返中使用 fixup! 提交的规范，合并脚本会负责自动 squash。
• contributing-docs/commit-message-guidelines.md：Angular 提交信息约定，是 PR 标题/分支管理工具解析的基础。
• contributing-docs/building-and-testing-angular.md：本地构建与测试环境准备，便于在提交前自行验证改动。
• packages/core/primitives：文档中特别提到的"须独立合并与同步"的受保护目录，可对照其结构理解隔离原因。