Ansible Stable 分支回迁（Backport）实战：六步工作流、Cherry-pick 细节与自动化脚本

Ansible 上游仓库采用"所有 PR 合入 devel 分支、再按策略回迁到 stable 稳定分支"的发布管理模式。本文基于仓库中的 Claude Code 技能文档 .claude/skills/creating-backports/SKILL.md 展开，完整梳理把一个已合并进 devel 的 Pull Request 回迁到 stable 分支的六步工作流：如何验证源 PR 与合并提交、如何确定回迁目标分支、如何用 git cherry-pick -x 创建回迁分支、如何规范地推送并创建 PR，以及遇到 cherry-pick 冲突时的恢复策略。读完本文，你可以独立完成一次完整的 backport 操作，并理解 Ansible 维护者为此准备的自动化工具链。

一、Backport 在 Ansible 分支模型中的位置

理解回迁工作流之前，先明确 Ansible 的分支与发布规则。仓库的贡献规范 context/contributing.md 在 "Branch and release management" 一节给出了明确约定：

• 所有 PR 的目标分支都是 devel；
• 报告 stable 发布版的问题前，必须先在 devel 上验证问题确实存在；
• Bug fixes: backported to latest stable only（普通 bug 修复只回迁到最新稳定分支）；
• Critical bug fixes: backported to latest and previous stable（关键 bug 修复回迁到最新和前一个稳定分支）；
• Security issues: contact [e-mail] privately, not via GitHub（安全漏洞必须私下报告，禁止通过 GitHub 公开渠道）。

这套策略正是 backport 技能第 3 步"确定回迁目标分支"的判定依据。回迁范围不是随意选择的：一个普通修复通常只产生 1 个 backport PR，而一个关键修复会产生 2 个。

二、技能文档：六步回迁工作流总览

.claude/skills/creating-backports/SKILL.md 是一个可被用户直接调用的 Claude Code 技能（frontmatter 中标注 user-invocable: true），其描述为"Create backports of a GitHub pull request that has merged into the devel branch in the upstream repository"。文档开篇即给出了一张进度清单，整个流程被拆成六个可跟踪的步骤：

Backporting Progress:
- [ ] Step 1: Verify the referenced pull request
- [ ] Step 2: Identify the git remote for the upstream repository
- [ ] Step 3: Determine the stable branches for the backport
- [ ] Step 4: Create the backport branches
- [ ] Step 5: Create pull requests
- [ ] Step 6: Summarize the work

下面逐步拆解每一步的命令与注意事项。

三、Step 1：验证源 PR 已合并并记录合并提交 SHA

回迁的起点是一个已经合并进 devel 的 PR 编号。第一步用 GitHub CLI 验证 PR 状态并提取 merge commit 的 SHA：

# 查看 PR 基本信息（确认 merged 状态与目标分支）
gh pr view <number>

# 直接输出合并提交的 OID（即后续 cherry-pick 要使用的 SHA）
gh pr view <number> --json mergeCommit -q .mergeCommit.oid

文档明确要求：如果 PR 未合并、或合并到了错误分支，必须中止（Abort）。这个前置校验看似简单，却决定了后续 cherry-pick 的对象是否正确——Step 4 的 cherry-pick 正是把第 1 步拿到的这个 merge commit SHA 应用到各 stable 分支上。

四、Step 2：识别 upstream remote 并同步本地 devel

本地仓库通常有两个远程：指向上游官方仓库的 remote（约定命名为 upstream）和指向自己 fork 的 remote（通常命名为 origin）。如果 upstream 不存在，工作流会先提示创建它。确认 remote 后，将本地 devel 分支与上游同步：

git fetch <upstream_remote>
git checkout devel
git pull --rebase <upstream_remote> devel

这里使用 --rebase 拉取，目的是保持本地 devel 与上游 devel 的提交历史线性一致，避免在后续基于它做操作时引入多余的 merge 提交。同步 devel 还有一个隐含作用：确保本地能拿到 Step 1 中记录的那个 merge commit（若本地落后于上游，cherry-pick 时会找不到该提交）。

五、Step 3：依据回迁策略确定目标 stable 分支

这一步把策略落地为具体的分支列表。先用 git ls-remote 列出上游所有 stable-* 分支：

git ls-remote --heads <upstream_remote> 'refs/heads/stable-*'

然后对照 context/contributing.md 的回迁策略判断：

修复类型	回迁目标
普通 bug 修复	仅最新一个 stable 分支
关键 bug 修复	最新 + 前一个 stable 分支
安全问题	不走回迁流程，直接私下报告 [e-mail]

文档强调：在继续之前必须询问用户该修复属于哪一类，并确认目标分支列表。这一步是人为确认点——自动化工具不应自行判断修复的严重程度。

六、Step 4：创建回迁分支并 cherry-pick 合并提交

这是整个流程中操作最密集、也最容易出错的一步。文档首先提醒：开始之前确认自己当前不在需要保留的分支上，因为后续会在多个分支之间反复创建和切换。

6.1 确保 stable 分支引用是最新的

git fetch <upstream_remote>

6.2 为每个目标 stable 分支创建回迁分支

分支命名遵循 backport/VERSION/PR_NUMBER 规范，且直接基于上游 stable 分支的远程引用创建：

git checkout -b backport/VERSION/PR_NUMBER <upstream_remote>/STABLE_BRANCH
# 示例：
git checkout -b backport/2.20/1234 upstream/stable-2.20

6.3 cherry-pick 合并提交（必须带 -x）

git cherry-pick -x <merge_commit_sha>

-x 选项会在提交信息中追加一行 (cherry picked from commit <sha>)，记录该提交的原始出处。这条注释不是可有可无的装饰：Ansible 的自动化工具依赖它来反向定位回迁 PR 的来源（后文第五节详述）。

6.4 冲突处理：中止、报告、等待

如果遇到合并冲突，文档给出的处理纪律非常严格：

1. 执行 git cherry-pick --abort 中止本次 cherry-pick；
2. 通知用户该 stable 分支需要人工解决冲突；
3. 向用户说明两个选项：a) 人工解决冲突（助手可协助指导）；b) 跳过该 stable 分支的回迁；
4. 不得在发生冲突后继续处理其余分支——必须等待用户决策。

这条"单点故障即暂停"的规则保证了部分成功场景的可控性：每个 stable 分支的回迁彼此独立，一个分支冲突不会污染其他分支的结果。

6.5 确认 fork remote 后再推送

推送前有两道安全检查：

• fork remote 通常命名为 origin，但必须用 git remote -v 验证它指向的是用户自己的 fork 而非上游仓库；
• 确认 remote 名称后再执行推送：

git push <fork_remote> backport/VERSION/PR_NUMBER
# 示例：
git push origin backport/2.20/1234

文档特别警告：绝不能向 upstream remote 推送——那相当于直接往官方仓库推分支，绕过了整个 PR 评审流程。

七、Step 5：为每个回迁分支创建 Pull Request

推送完成后，需先经用户确认，再为每个回迁分支创建 PR。标题带 stable 分支前缀、正文记录来源 PR 与 cherry-pick 提交，格式均有约定：

gh pr create \
  --base stable-2.20 \
  --title "[stable-2.20] Fix bug in module" \
  --body "Backport of PR #1234

(cherry picked from commit abc123)"

要点归纳：

• --base 指向被回迁的 stable 分支名；
• 标题格式为 [STABLE_BRANCH_NAME] 原始PR标题，前缀让维护者在 PR 列表里一眼识别回迁件；
• 正文两行结构：第一行声明"Backport of PR #XXXX"，第二行保留 (cherry picked from commit ...) 注释——这两行共同构成自动化追踪的锚点。

八、Step 6 与错误恢复：汇总、清理与重试

收尾汇总：流程结束时必须向用户给出所有已创建 PR 的 URL 清单，让结果可核查、可追踪。

错误恢复（Error Recovery） 部分定义了三种失败场景的处置方式：

故障场景	处置策略
Cherry-pick 冲突	列出哪些分支成功、哪些因冲突失败
PR 创建失败	清理未转化为 PR 的"孤儿"分支
部分成功	汇总已成功项，提供对失败分支逐个重试的选项

这与 Step 4 中"冲突即暂停"的纪律呼应：回迁流程被设计成幂等且可断点续做的——失败的分支清理后可以单独重试，不会阻塞其他分支。

九、仓库内的配套工具：backport 自动化脚本

除了手工工作流，Ansible 仓库在 hacking/backport/ 目录中提供了一套维护 backport 的 Python 脚本（依赖 pygithub，需要环境变量 GITHUB_TOKEN）。其核心是 hacking/backport/backport_of_line_adder.py：当某个 backport PR 已经手工创建但正文缺少来源标注时，该脚本可以把 "Backport of ..." 引用行补写进 PR 描述。

用法（见 hacking/backport/README.md）：

./backport_of_line_adder.py <backport> <original PR>
# 第二参数传 auto 可让脚本自动推断原始 PR：
./backport_of_line_adder.py 12345 auto

从源码看，auto 模式的推断逻辑分三层（backport_of_line_adder.py 中 search_backport() 函数）：

1. 标题匹配：正则 PULL_BACKPORT_IN_TITLE 捕获形如 fix (#12345) 或 fix (backport of #54321) 的标题写法；
2. 正文 cherry-pick 行匹配：正则 PULL_CHERRY_PICKED_FROM 匹配 cherry-picked from commit XXXXX 行（这正是第六节强调 git cherry-pick -x 必要性的原因——它生成的注释行被脚本正则 '\(?cherry(?:\-| )picked from(?: ?commit|) (?P<hash>\w+)...' 直接消费），再通过 get_prs_for_commit() 用 GitHub 提交搜索 API（hash:<commit> org:ansible org:ansible-collections）反查该提交所属的原始 PR；
3. 正文 PR 引用匹配：捕获正文中的 #nnnnn、user/repo#nnnnn 以及完整 PR URL。

写入位置也有讲究：generate_new_body() 会把引用行加到 PR 正文中 SUMMARY 标题正下方（符合 Ansible PR 模板的结构），找不到 SUMMARY 行则追加到正文末尾；若正文已存在 "Backport of http" 行则直接抛异常中止，防止重复写入。脚本在真正修改前会打印候选来源 PR 并等待用户确认（prompt_add()），体现了与 SKILL 文档一致的人为确认点设计。

十、实操要点清单

把整套工作流的纪律浓缩为可执行清单：

1. 先验证后操作：gh pr view <number> --json mergeCommit -q .mergeCommit.oid 确认 PR 已合并进 devel，记下 merge SHA；
2. 同步 devel：git fetch upstream && git checkout devel && git pull --rebase upstream devel；
3. 确认回迁范围：按 context/contributing.md 的策略向用户确认修复类型与目标分支，用 git ls-remote --heads upstream 'refs/heads/stable-*' 列出候选；
4. 逐分支操作：git checkout -b backport/VERSION/PR upstream/stable-VERSION → git cherry-pick -x <merge_sha> → 冲突则 --abort 并暂停等待；
5. 安全推送：git remote -v 确认 origin 指向自己的 fork 后再 git push origin backport/VERSION/PR；
6. 规范建 PR：标题 [stable-X.Y] 原标题、正文含 "Backport of PR #XXXX" 与 "(cherry picked from commit ...)" 两行；
7. 收尾：汇总所有 PR 链接；失败分支清理孤儿分支后可单独重试。

遵循这套约定，回迁产生的每一个 PR 都能在标题、正文和提交历史三处留下可机器解析的来源信息——这既是 Ansible 分支模型的维护纪律，也是仓库内 backport 自动化工具能够生效的前提。