语义化版本的自动化,本质上是把“下一版该发多少”交给 commit 消息决定。按照 Conventional Commits 的对应关系,feat 发 minor,fix 发 patch,带 BREAKING CHANGE: 的 commit 发 major;semantic-release 的 commit analyzer 读的也是消息本身,不看这个 commit 改了哪些文件。

这套做法建立在一个前提上:写 commit 的人理解每种类型对版本号的影响。现在 commit 越来越多地由 coding agent 撰写,这个前提就松动了。代理写下 feat,可能只是觉得这次“加了东西”;在 monorepo 里修好文档网站的一个错误写成 fix(site),分析器照样把它算作包的 patch;给一段重构补上 BREAKING CHANGE: 脚注,下一次合并就会直接发出 major。规则本身都没有被违反,版本却已经不是维护者想发的版本。

另一个前提落在工具上。常见的组合是 semantic-release 负责发布、commitlint 负责检查 commit,再加上 changelog preset 生成 release notes。三个工具各有配置格式,同一套类型规则要分别写进 release.config.js、commitlint.config.js 和 preset;规则改了,得同时确认它在检查、版本分析和 release notes 三处的效果一致。对代理来说,规则散落在配置文件和插件之间,也很难从一个地方读到“这个类型会发什么版本”。

aronrepo 是我为这个问题做的工具:让代理和维护者遵循同一份规则,并由规则拦下会误发的 commit,而不是依赖代理自己的判断。

一个包,一套固定的规则

aronrepo 把 commit 检查、版本规划、release notes、npm 发布和 GitHub Release 放进同一个包,不需要另外安装 semantic-release、commitlint 或 conventional-changelog。

要在自己的项目中使用,可以前往 aronrepo GitHub 仓库,复制 README 的“AI Coding Integration”中的安装提示,粘贴给 coding agent,让它根据项目环境完成接入。

这套设计做了几个取舍。

类型固定,每种类型只有一个含义

项目不能新增或重命名 commit 类型。Feat 是新能力,Improve 是改进现有能力,Fix 是已发布行为的错误修复,Upgrade 是运行时依赖的变更,Chore 是维护工作;Docs、Test、Build、CI 等类型不发布。类型不在列表中、或摘要以句号结尾的 commit,aronrepo check 会拒绝并给出合格的标题。类型与 scope 不区分大小写,fix(core): repair cache 和 Fix(Core): Repair cache 是同一个 commit,release notes 会把句首转成大写;从 Conventional Commits 迁移的项目,大多数 commit 可以沿用原来的写法。

固定类型牺牲了各项目的自定义空间。我接受这个代价,因为类型一旦可以自定义,代理就得先读懂每个项目的方言;固定之后,它只要判断这次改动属于哪一类,发布级别由规则决定。

minor 与 major 由所有者决定

默认的 explicit 模式下,除了 Bump(Minor) 和 Bump(Major),所有类型最多只发 patch,BREAKING CHANGE: 脚注会被拒绝。也就是说,代理写 Feat 最多发一个 patch,要发 minor 或 major,必须有一个明确的 Bump commit。需要 Conventional Commits 行为的项目可以改用 auto 模式,让 Feat 发 minor、破坏性脚注发 major。

两种模式的区别,在于版本号对用户意味着什么。

两台相同的木制三刻度计数器并排:左边两个较大的刻度被铜条和挂锁固定,钥匙放在桌上,纸卡只能带动最小的刻度;右边的纸卡通过齿轮同时连到三个刻度。
左边是 explicit:纸卡只推动 patch,minor 与 major 要等所有者开锁。右边是 auto:commit 类型通过齿轮直接决定哪一位前进。

explicit 适合把 minor 与 major 当作对外发布的项目,例如有公开迁移指南的框架、设计系统或 UI 组件库。这类项目的 major 通常伴随迁移文档、公告与兼容期,minor 可能对应一次版本说明或文档改版,时间点由所有者安排。日常合并的功能与修复以 patch 持续发出,积累到准备对外说明时,再推一个 Bump(Minor)。Bump 不受发布路径检查限制,可以是一个空 commit,例如 git commit --allow-empty -m "Bump(Minor): Release the new theme API"。代价是新功能会先以 patch 出现:用 ~ 范围锁定 patch 的用户也会收到新增的 API,按照语义化版本的严格定义,这应该是 minor。

auto 适合版本号主要给工具和依赖范围读、而不是给人看的项目,例如团队内部共享的包、供自家应用使用的 SDK,或功能简单的 CLI 与 utility。用户依靠 ^ 范围自动升级,需要版本号准确反映“有没有新 API、有没有破坏兼容”,而不需要有人为每个 minor 安排时间。这时 commit 类型与 BREAKING CHANGE: 脚注会直接变成版本号,PR 评审就必须把 commit 标题和脚注也纳入;CI 中的 aronrepo check --title 能拦下格式错误,却无法判断一项改动是否真的破坏兼容。

模式本身也由所有者决定。aronrepo 给代理的规则写明:引入时必须询问所有者使用哪种模式;在已引入的项目中,除非用户在当前对话中要求,代理不能写 Bump(Major)、Bump(Minor) 或破坏性标记。

没改到发布文件的 commit 不发布

aronrepo 用发布路径判断一个 commit 有没有碰到会发布的内容。默认是公开 workspace 包的目录,排除测试、fixture、benchmark、示例和 changelog 等。发布类型的 commit 如果没有改动任何发布路径,aronrepo check 会在合并前拒绝,也不会发布。前面提到的 Fix(Site),就会被要求改成不发布的类型。

一排白色纸卡分别画着包裹、网页窗口和试管图标,经过木框金属筛网:包裹卡片进入木箱,网页和试管卡片沿着金属轨道排进一旁的白色纸盒。
只有改到发布包内容的 commit 会进入发布;网站和测试的改动照样合并,但不会触发版本。

每个决定都有理由

aronrepo explain 会列出下一个版本,以及每个 commit 为什么发布或不发布;aronrepo release 发布时也会记录同样的判断,--dry-run 则只输出计划和 release notes。代理在推送到发布分支前可以先跑 explain,维护者评审 PR 时看到的也是同一份结论。explain --json 还会输出要发布的 commit(head)和完整的 release notes,CI 可以把它写进 job 摘要,让评审的正是实际会发布的内容。

中断的发布可以接着完成

monorepo 的发布经常在中途失败:部分包已经上了 npm,tag 却还没推送。aronrepo release 先把所有包发布到临时的 dist-tag,确认 registry 都能获取后才移动正式的 dist-tag,接着推送 tag、创建 GitHub Release。重新运行同一个 job 时,已从同一个 commit 发布的版本会跳过,缺少的 tag 或 release 会补上。版本号只从 vX.Y.Z tag 读取,不会把版本写回 package.json 再 commit。

什么时候发布,可以交给维护者

推送即发布只是默认的 CI 写法。有固定上线周期的项目,常希望 PR 持续合并到 main、测试环境照常部署,正式版则等维护者决定时间。这类需求不必另开 release 分支,也不需要 Release PR:aronrepo 的版本是从上一个 tag 算到要发布的那个 commit,周一到周四合并的四个 Fix,周五才发布时仍然是一个 patch,release notes 一次列出四条。

要改的是触发方式。main 每次推送只执行 explain --json,把版本、commit 与 release notes 写进 job 摘要;正式发布改成手动触发的 workflow,输入预览中的 commit 与版本,并挂上设置了 required reviewers 的 GitHub Environment,批准记录留在 GitHub 的部署历史里。发布步骤执行:

aronrepo release --branch main --expect 1.2.4

release 会先确认检出的 commit 确实在 origin/main 上,避免把 feature 分支的 commit 当成 main 发布;--expect 则在发布时重新计算,版本与批准时看到的不同就停止,不会发布任何内容。下一次发布从这个 tag 接着算,批准之后才合并的 commit 留到下一版。完整的 workflow 示例在 aronrepo 的 README。

给代理的不是文档,而是数据

只把规则写进 README,代理仍然需要读懂并记住。aronrepo 让同一份策略有三个出口:

  • aronrepo policy --json 输出当前项目的模式、发布路径、每种类型的发布级别与说明。
  • aronrepo agents --write 把策略区块写进 AGENTS.md,命令按项目的包管理器生成;区块过期时,aronrepo agents 和 aronrepo doctor 会失败,没有人需要手动复制类型表。
  • aronrepo check 在 commit-msg hook、PR 的每个 commit 和 PR 标题上执行同一套检查。标题不合格时,它会给出建议的写法。

README 还附了一段可以直接贴给 coding agent 的引入提示:先检查项目、询问所有者使用哪种模式、移除 semantic-release 与 commitlint、加上 hook 和 CI,最后运行 doctor、explain 与 release --dry-run 报告下一个版本。引入工作本身则使用 Build、CI、Chore(Agent) 这类不发布的类型。

与 semantic-release、release-please、changesets 比较

JavaScript 项目常见的发布工具还有另外两种做法。release-please 同样读取 Conventional Commits,但不直接发布,而是维护一个 Release PR,合并时才创建 tag 与 GitHub Release;changesets 则完全不看 commit 消息,由开发者为每个变更附上一份 changeset 文件,写明要发 patch、minor 还是 major。

项目aronreposemantic-releaserelease-pleasechangesets
版本依据固定的 commit 类型commit 消息(默认 Angular 约定,可换 preset)Conventional Commits 消息另外编写的 changeset 文件
minor、major 由谁决定explicit:所有者写 Bump;auto:commit 类型commit 类型与 BREAKING CHANGEcommit 类型与 !,可用 Release-As 指定版本每份 changeset 声明的级别
何时发布默认推送到发布分支即发布;也可手动触发,发布维护者批准的 commit推送到发布分支即发布合并 Release PR 时执行 changeset version 与 publish,通常通过 Version Packages PR
版本号存放只在 git tag,不写回 package.jsongit tag;写回需另装 @semantic-release/git,官方不推荐Release PR 写入 package.json 与 manifestchangeset version 写入 package.json
Release notesGitHub Release 正文GitHub Release 正文;CHANGELOG.md 需另装插件CHANGELOG.md 与 GitHub Release各包的 CHANGELOG.md
commit 检查内置 check:hook、PR 的每个 commit 与 PR 标题无,需另装 commitlint无不看 commit;changeset status 可检查是否缺少 changeset
没改到发布文件的发布类型 commit合并前拒绝,不发布按消息照常发布单个包照常发布;monorepo 按变更路径归属到包不适用,是否发布由 changeset 决定
monorepo支持,所有包共用一个版本核心一次发布一个包,monorepo 需依靠社区插件manifest 配置,各包独立版本,可联动主要设计对象,各包独立版本,可用 fixed、linked 绑定
发布到 npm内置,先发布到临时 dist-tag,全部就绪才切换内置(@semantic-release/npm)不负责,工作流需另写发布步骤内置 changeset publish,只发布 npm 上还没有的版本
预发布alpha、beta、rc、canary 分支预发布分支与 channelprerelease 配置pre enter、pre exit 模式与 snapshot
中断后重跑补上缺少的发布、tag 与 Releasetag 在发布前推送,发布失败需手动补救不负责发布重跑 publish 会跳过已发布的版本
发布前预览explain(--json 含 commit 与 release notes)、release --dry-run--dry-runRelease PR 本身changeset status
给代理的规则policy --json、生成 AGENTS.md 区块无无无
适用范围JavaScript,只发布到 npm多语言,依靠插件多语言,各语言有对应 strategyJavaScript 包管理器的 workspace

放到代理写 commit 的场景里,四者的区别在于“谁在什么时候定下版本级别”。semantic-release 由 commit 消息当场决定,合并即发布;release-please 同样由消息决定,但 Release PR 让人在发布前再看一次版本号与 changelog;changesets 把级别写在 changeset 文件里,如果由代理负责写 changeset,级别也就由代理来选,靠 PR 评审把关;aronrepo 则在 explicit 模式下把 minor 与 major 从代理手上拿走,并在合并前拒绝不该发布的 commit。

如果需要各包独立版本,changesets 更合适;需要多语言支持,或想在 GitHub 界面里通过合并 PR 完成发布确认,release-please 更合适;需要 npm 以外的发布目标或特定插件,semantic-release 的生态最完整。

安装规模

把功能收进一个包,依赖也随之减少。下面的数字是在全新目录分别执行 npm install --ignore-scripts 的结果:包数量取 npm 报告的 added 数,大小取 node_modules 的 du。semantic-release 单独安装不包含 commit 检查,与 aronrepo 覆盖范围相当的是“semantic-release 加 commitlint”这一组;release-please 与 changesets 不检查 commit,测量的是它们本身的 CLI。

项目aronreposemantic-releaserelease-pleasechangesets
测量的包aronrepo(当日最新版)semantic-release 25.0.9release-please 17.11.2@changesets/cli 3.0.3
Node.js 要求22.18 及以上^22.14 或 24.10 及以上22 及以上^22.11、^24 或 26 及以上
直接依赖4283121
安装后的包总数7301(加 commitlint 为 345)16240
node_modules 大小2.7 MB79 MB(加 commitlint 为 105 MB)93 MB3.7 MB
主包解压大小366 kB128 kB929 kB89 kB

安装后的包总数

npm install --ignore-scripts · added · 2026-11-07

aronrepo 安装 7 个包,changesets 40 个,release-please 162 个;与 aronrepo 覆盖范围相近的 semantic-release 加 commitlint 安装 345 个。

安装的包数量
  • aronrepo7
  • changesets 3(@changesets/cli)40
  • release-please 17162
  • semantic-release 25(不含 commit 检查)301
  • semantic-release 25 + commitlint345
查看包数量数据表
安装后的包总数 · 安装的包数量
安装组合安装的包数量
aronrepo7
changesets 3(@changesets/cli)40
release-please 17162
semantic-release 25(不含 commit 检查)301
semantic-release 25 + commitlint345

2026 年 11 月 7 日在全新目录执行 npm install --ignore-scripts,取 npm 报告的 added 数。commitlint 组合包含 @commitlint/cli 与 @commitlint/config-conventional。

测量方式

node_modules 大小

npm install --ignore-scripts · du node_modules · 2026-11-07

aronrepo 的 node_modules 约 2.7 MB,changesets 约 3.7 MB;release-please 约 93 MB,semantic-release 加 commitlint 约 105 MB。

MB(du 测量)
  • aronrepo2.7
  • changesets 3(@changesets/cli)3.7
  • release-please 1793
  • semantic-release 25(不含 commit 检查)79
  • semantic-release 25 + commitlint105
查看安装大小数据表
node_modules 大小 · MB(du 测量)
安装组合MB(du 测量)
aronrepo2.7
changesets 3(@changesets/cli)3.7
release-please 1793
semantic-release 25(不含 commit 检查)79
semantic-release 25 + commitlint105

与上图为同一次安装,用 du 测量 node_modules;不同文件系统的块大小会让数值略有差异。

测量方式

与覆盖范围相当的 semantic-release 加 commitlint 相比,包数量从 345 降到 7,大小从约 105 MB 降到约 2.7 MB。aronrepo 主包本身其实比 semantic-release 大(解压后约 366 kB 对 128 kB),因为 commit 检查和 CLI 都包含在内;差距几乎全部来自依赖树。aronrepo 的直接依赖只有 semver、js-yaml、picomatch 和 tinyglobby 四个。

changesets 同样轻量,因为它不解析 commit,也不创建 GitHub Release,这部分交给另外的 GitHub Action。release-please 的 CLI 安装规模接近 semantic-release,但多数项目通过官方 GitHub Action 运行,不会进入项目的依赖。

适用条件与代价

aronrepo 的范围是刻意收窄的。它只支持 ESM,需要 Node.js 22.18 及以上;同一个仓库里所有发布的包共用一个版本号;打包使用项目的包管理器,发布一律通过 npm。想自定义 commit 类型、让各个包各自升版本,或使用 npm 以外的 registry 流程,都不在它的设计范围内。

已经有自己一套发布安全流程的项目,也不必整体替换。CLI 背后的函数由 aronrepo/node 导出,commit 规则、版本与 release notes 的工具函数则由 aronrepo 导出;可以只让 aronrepo 决定版本、tag 与 notes,打包、验证和上传仍交给原有脚本。

我把 aronrepo 的重点放在一件事上:把版本决策从“写 commit 的人判断得对不对”,转移到“规则能不能在合并前拦下来”。代理照样会选错类型,区别在于选错时,check 会拒绝它并给出替代写法,而 minor 与 major 始终需要所有者明确写下。