跳转到文档内容
版本：Next

如何进行 PR 的 Cherry-pick 操作

本文档解释了在 karmada-io/karmada 仓库的 release branches 中如何管理 cherry-pick 操作。 该任务的常见使用场景是将已经合并到主分支（master）的 PR 回合（backport）到某个发布分支。

本文档参考自 Kubernetes cherry-pick 指南。

前置条件​

  • 一个已合并到 master 分支的 Pull Request。
  • 发布分支已存在（例如：release-1.0）。
  • 已配置 Git 和 GitHub Shell 命令行环境，用于向您在 GitHub 上的 Karmada 个人 fork 仓库推送代码，以及向已配置的上游远程仓库（upstream）发起拉取请求（pull request）。该上游仓库追踪 https://github.com/karmada-io/karmada.git 代码库，且环境包含 GITHUB_USER 环境变量。
  • 安装了 GitHub CLI 工具（gh），参考安装说明。
  • 一个 GitHub 个人访问令牌（Personal Access Token），需具备 “repo” 和 “read:org” 权限。该令牌仅用于执行 gh auth login 登录，不涉及 cherry-pick 之外的操作（如创建分支和发起 PR）。

适合进行 Cherry-pick 的 PR 类型​

相较于主分支每天合并大量 PR，发布分支的 cherry-pick 数量通常少一个到两个数量级，这是由于其需要更高程度的审查。

重点应放在关键性 Bug 修复上，例如：

  • 数据丢失

  • 内存损坏

  • 程序 panic、崩溃或卡死

  • 安全性漏洞

如果是某个 alpha 特性的功能问题修复（不涉及数据或安全问题），通常不视为关键性修复。

如果您准备进行 cherry-pick，且该改动不是明显关键的 bug 修复，请慎重考虑。如仍决定继续，请通过以下补充信息增强您的理由：

  • 一个描述问题的 GitHub Issue

  • 改动范围说明

  • 引入该改动的风险分析

  • 回归风险评估

  • 已完成的测试及新增测试用例说明

  • 关键干系人（reviewer/approver）对该变更回移必要性的背书

我们鼓励社区广泛参与对功能增强的讨论。如果某个已发布的特性在某个平台上未启用，这是社区在 master 分支阶段的疏漏，应在后续主版本中修复，而不应通过补丁版本进行回移。

发起 Cherry-pick 操作​

有两种方式可以发起 cherry-pick：使用 cherry-pick 脚本，或使用 Prow 的 cherry-picker 插件。

使用 Cherry-pick 脚本​

  • 执行 cherry-pick script

    例如，将 PR #1206 从 master 回移到远程分支 upstream/release-1.0：

    hack/cherry_pick_pull.sh upstream/release-1.0 1206

    • 注意，该脚本默认您已配置名为 upstream 的 git 远程源，指向 Karmada 官方仓库。

    • 每一个目标发布分支需要单独执行一次 cherry-pick 脚本。请确保将修复应用于所有受影响的活跃发布分支。

    • 若未设置环境变量 GITHUB_TOKEN，脚本将提示输入 GitHub 密码：此处应提供您的 个人访问令牌，而非 GitHub 账户密码。为了避免交互式输入，建议将令牌安全地设置为环境变量 GITHUB_TOKEN。可参考此问题评论。

使用 Prow cherry-picker 插件​

除了使用 cherry-pick 脚本外，Karmada 的 Prow 机器人现已提供 cherry-picker 插件， 可自动为您创建 cherry-pick PR。

使用方法很简单，只需在 Pull Request 中留言并指定目标发布分支，例如：

/cherry-pick release-1.18

在该 Pull Request 合并后，机器人会自动向指定的发布分支创建 cherry-pick PR。 如果补丁无法干净地应用，机器人会在评论中报告失败，此时您需要回退到 cherry-pick 脚本方式。

如需 cherry-pick 到多个发布分支，有两种留言方式：

  • 每个发布分支单独一行（推荐），这样将为不同分支并行创建 cherry-pick PR：

    /cherry-pick release-1.18
    /cherry-pick release-1.17
    /cherry-pick release-1.16

  • 将多个发布分支放在同一行，以空格分隔。这种方式下 cherry-pick PR 将串行创建： 机器人先创建第一个分支的 PR，等其合并后再创建下一个分支的 PR，依次进行：

    /cherry-pick release-1.18 release-1.17 release-1.16

关于该命令的更多说明，请参阅 Prow 命令帮助。

Cherry-pick 的评审流程​

与普通 Pull Request 一样，cherry-pick PR 也需代码 OWNERS 审核并使用( /lgtm) 和 (/approve) 进行批准。

同样适用常规 PR 的 Release Note 要求，但 cherry-pick PR 的 Release Note 内容将自动继承自原始 PR（来自 master 分支）。

Cherry-pick 问题排查​

发起 cherry-pick 时可能遇到以下问题：

  • cherry-pick PR 无法干净地应用于旧的发布分支：需手动解决冲突。

  • PR 包含的代码未通过 CI 检查：需从自动生成的分支中检出、修改问题提交并强制推送回该分支；或者可以新建一个 PR（推荐优先修复原分支，避免冗余 PR）。

不再受支持版本的 Cherry-pick​

对于已不再由社区支持的发布版本，其是否需要打补丁需社区进行讨论和决策。

编辑本页
最近更新时间 在 由 Hongcai Ren