backportcheck

backportcheck

修复先进入最新版本线，随后便会出现更棘手的问题：仍在使用的旧版发布分支中，哪些也需要这个修复？凭直觉判断，要么会漏掉一个暗中受影响的分支，要么会把修复回移到所有分支，给发布团队增加负担。backportcheck 将这一决策转化为固定且可审计的流程：提供修复，它就会返回计划。

首先，筛选出真正符合条件的候选分支。分支必须同时满足以下三项才符合条件：仍受支持；版本严格早于修复进入的版本；并且，如果你指定了引入 bug 的版本，该分支的版本必须不早于该版本，因为早于 bug 引入时间的分支不可能包含这个 bug。版本采用普通的 x.y.z 数字格式，按组件逐个进行数值比较，因此 1.10.0 会正确排在 1.9.0 之后。

每个未通过筛选的分支仍会出现在报告中，并且只会有一个原因。原因按固定顺序检查，确保报告不会归咎于错误原因：不受支持的分支标记为 unsupported，即使它也过新；其次是 not older than fix version；最后是 predates bug introduction。

然后，根据严重程度为每个候选分支指定操作：

• critical — 所有候选分支都标记为 backport。关键修复会回移到所有符合条件的分支。
• major — 与修复属于同一主版本线的候选分支标记为 backport；属于更早主版本线的候选分支标记为 consider。
• minor — 与修复属于同一主版本线的候选分支标记为 consider；属于更早主版本线的候选分支标记为 skip。

只有至少一个候选分支的操作为 backport 时，needs_backport 才为 true。计划和跳过列表都会按版本降序排序；版本相同时，按分支名称升序排列，因此最新的分支（通常也是最紧急的分支）会排在前面。格式错误的输入会触发验证错误，并指出出错路径：版本不是 x.y.z、严重程度不属于枚举值，或分支条目缺少名称、版本或 supported 标记。计算完全纯本地：不会联网，不读取或访问配置和代码仓库；backportcheck 只负责制定计划。

命令行

npx @reneturcios/backportcheck check --input args.json
npx @reneturcios/backportcheck --version

args.json 包含完整的参数对象：

{
  "fix_version": "3.2.0",
  "severity": "major",
  "introduced_in": "2.4.0",
  "branches": [
    { "name": "release-3.1", "version": "3.1.4", "supported": true },
    { "name": "release-3.0", "version": "3.0.9", "supported": true },
    { "name": "release-2.5", "version": "2.5.1", "supported": true },
    { "name": "release-2.3", "version": "2.3.8", "supported": true },
    { "name": "release-1.9", "version": "1.9.0", "supported": false }
  ]
}

结果以 JSON 格式输出：

{
  "needs_backport": true,
  "fix_version": "3.2.0",
  "severity": "major",
  "plan": [
    { "branch": "release-3.1", "version": "3.1.4", "action": "backport" },
    { "branch": "release-3.0", "version": "3.0.9", "action": "backport" },
    { "branch": "release-2.5", "version": "2.5.1", "action": "consider" }
  ],
  "skipped_branches": [
    { "branch": "release-2.3", "version": "2.3.8", "reason": "predates bug introduction" },
    { "branch": "release-1.9", "version": "1.9.0", "reason": "unsupported" }
  ]
}

退出代码：成功时为 0，运行时错误时为 1（包括输入文件无法读取或无效，以及输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/backportcheck mcp

MCP 客户端配置：

{
  "mcpServers": {
    "backportcheck": {
      "command": "npx",
      "args": ["-y", "@reneturcios/backportcheck", "mcp"]
    }
  }
}

工具

• check_backport — 判断修复是否需要回移，以及应回移到哪些发布分支。

  • fix_version（string，必填）— 修复进入的版本，格式为 x.y.z
  • severity（string，必填）— 以下值之一：critical、major、minor
  • branches（array，必填，不能为空）— 发布分支，每项为 {name, version, supported}，其中 name 是非空字符串，version 的格式为 x.y.z，supported 为布尔值
  • introduced_in（string，可选）— 引入 bug 的版本，格式为 x.y.z

  返回 {needs_backport, fix_version, severity, plan, skipped_branches}。

Docker

docker run -i ghcr.io/cloudcorprecords/backportcheck
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/backportcheck check --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios