Bump:发版前的版本号对齐(三段式发版的第一段)
职责边界(三段式;2026-09-21 修订:remote main 恢复分支保护、锁定直推,bump 从「main 直改直推」改为「bump 分支 + PR + CI」——与 dev-workflow 2026-09-21 版对齐):
| 段 | 动作 | 执行者 |
|---|---|---|
① /bump |
对齐 main → 建 bump 分支改齐版本号 → 自动衔接 /add(预检 + git add)→ 预检完全干净时继续自动衔接 /commit(push + 建 PR + auto-merge,2026-10-02 起) |
本 skill |
| ② CI | 远端 CI 跑全量,绿后 GitHub 自动 squash 合并进 main | GitHub Actions |
③ /release |
在最新 main 上打 tag + 发 Release(2026-10-02 起由 commit skill 第 10 步自动衔接) | release skill |
为什么走分支 + PR:main 已锁定直推(2026-09-21 起),版本号文件改动与其它内容一样经 PR + CI 进 main——CI 顺带验证 bump 没碰坏任何东西(版本文件也是回归面)。功能分支永不 bump 的纪律不变——多个并行分支各自 bump 必然冲突,版本号只在发版时经 bump 分支统一改。
执行流程
对齐 main(在主工作区执行;不要在 worktree 里
git switch main——会 fatal):git -C <主工作区> fetch origin && git -C <主工作区> merge --ff-only origin/main(以 origin/main 为准;主工作区就在 main 且干净时等价于pull --ff-only)。- 本地 main 与远端分叉(本地领先 / 历史不一致)→ 暂停报告,等用户确认对齐方式(对齐操作由用户执行或明确授权,本 skill 不自行 reset / force);
- 用户在功能分支上触发
/bump→ 提示:先让该功能分支的 PR 合并进 main(版本号不写在功能分支上),再来 bump。
建 bump 分支(从最新 main 开出):
- worktree 场景(会话 cwd 在主工作区、主工作区就是 main,也是本链条的实际常态)→ 新建专用 worktree:
git -C <主工作区> worktree add ../<仓库名>-bump-v<目标版本> -b chore/bump-v<目标版本>;后面第 4 步的文件改动全部落到该 worktree,不动主工作区(local main 只负责生成 worktree 与被快进同步)。 - 主工作区场景(用户就在非 main 的会话里手动触发)→
git switch -c chore/bump-v<目标版本>。
- worktree 场景(会话 cwd 在主工作区、主工作区就是 main,也是本链条的实际常态)→ 新建专用 worktree:
判定新版本号(发布状态必须实测,不凭 VERSION / CHANGELOG / commit 历史推断):
- 实测最新已发布版本:
gh release list --limit 1(或gh release view v<版本>查重); - CHANGELOG 顶部条目的版本号高于已发布版本 → 新版本号 = 该条目版本号(CHANGELOG 已定稿,bump 只做各文件对齐);
- 无待发布条目 → 从当前 VERSION 起按待发布改动性质定幅度(新增功能 → minor;仅修复 / 文档 → patch;build 号体系按既有序列 +1,如
3.8.1-32→3.8.1-33),并在 CHANGELOG 顶部新建该版本条目(## [<新版本号>] - <今天日期>,依据近期 commit 补简要摘要;不改已发布版本的历史条目)。
- 实测最新已发布版本:
在 bump 分支上改齐版本号(以新版本号同步所有版本号载体,存在的才改):
VERSION(纯数字 + 换行,无v前缀);package.json顶层version;package-lock.json顶层version(不动 packages 内依赖版本);- CHANGELOG 顶部条目版本号与日期(第 3 步已定);
- 主 manifest:
manifest.json/pyproject.toml/Cargo.toml/*.csproj; - README(
README.md/README_cn.md)显式声明当前版本的文字与版本徽章里的版本号(不抓 changelog 历史版本、不抓依赖版本);安装命令用固定 tag URL(releases/download/<tag>/<asset>)的,其版本号(tag 段与资产名)一并同步到新版本——遇到releases/latest/download/形式的存量链接顺手改为固定 tag 形式(latest 指针随发布移动、资产名带版本号,历史链接必 404,2026-09-08 用户裁定弃用,规范详见 release skill「安装链接」一节)。 - 项目无
VERSION文件而以 package.json 为版本源时,跳过 VERSION(不强制创建——创建属 commit skill 第 9m 的职责范围)。
自动衔接 /add(2026-10-02 用户立):本 skill 改完版本号文件后,直接进入 add skill 完整流程——以第 4 步的「改动文件清单」为候选集(只处理 bump 改动的版本号载体文件、不扫工作区其它改动),并把 bump 工作区路径一并传给 add skill(worktree 场景下其所有 git 命令用
git -C <bump 工作区>执行,见 add skill「worktree 场景」节):- add 预检(gitleaks + AI 语义扫描)完全干净 → add skill 按其第 7 步继续自动衔接 commit skill(push bump 分支 + 建 PR + enable auto-merge → 9z 等待 CI 合并、对齐本地 main → 第 10 步自动衔接
/release完成发版)——整条链自动跑完; - 有任何「需人工过目」/「不建议入库」内容 → 链条停在 add 报告阶段(干净文件已入暂存区),等用户处理后再推进(重新
/add或/commit); - 本 skill 自身仍不执行
git add/git commit(由 add / commit skill 按各自授权执行); - 逃生口:用户当轮明确说「只 bump、不要提交」时,不衔接、按旧例输出以下指引供用户手动执行:
git add <改动文件清单> /commit (commit skill 自动:commit → push chore/bump 分支 → 建 PR)- add 预检(gitleaks + AI 语义扫描)完全干净 → add skill 按其第 7 步继续自动衔接 commit skill(push bump 分支 + 建 PR + enable auto-merge → 9z 等待 CI 合并、对齐本地 main → 第 10 步自动衔接
链条中的 auto-merge:commit skill 建 PR 时已顺手 enable auto-merge(
gh pr merge --squash --auto --delete-branch)——CI 绿 + up-to-date 后自动合并进 main;本 skill 不重复操作。若 auto-merge 被挡(分支冲突 / 分支过期),按 commit 汇报的提示处理。汇报:新版本号与幅度判定依据(CHANGELOG 定稿 / 待发布改动性质)、改动文件清单(旧值 → 新值);并说明已自动衔接
/add(→/commit→/release)链条——提交推送、PR、CI 合并、自动发版的结果连在本次汇报中一并呈现(无需手动/add、/commit、/release,2026-10-02 起)。
边界
- 不打 tag、不发 Release(由链条中的 commit skill 第 10 步自动衔接
/release完成——2026-10-02 起;/release会自行对齐 main 并校验); - 不在功能分支上 bump、不直接 push main(远端已锁定,2026-09-21 起)、不修改 CHANGELOG 已发布版本的历史条目;
- 改动只限版本号载体文件(VERSION / package.json / package-lock.json / CHANGELOG 版本条目 / manifest / README 版本声明与徽章),不夹带其它改动。
- 由 commit skill 第 10 步发起的自动衔接只在「自最新 tag 以来含 fix / feat 类改动」时发生(2026-10-13 用户立:仅核心功能修复 / 新增触发发版,纯文档 / 杂事类不发版、不 bump);发版链内部延续(如 bump → add → commit → 第 10 步收尾)不受门禁二次拦截;用户主动
/bump不受此限。