assistant-ui 仓库的 Changesets 版本发布体系:从 .changeset 目录到 npm 自动发布
assistant-ui 仓库的 Changesets 版本发布体系:从 .changeset 目录到 npm 自动发布
本指南以仓库根目录
.changeset/README.md为入口,讲解 Changesets 如何在 assistant-ui 这个超大型 pnpm monorepo 中驱动版本管理与 npm 发布。读完你将掌握:.changeset/目录与 changeset 文件的结构规范、pnpm changeset的完整工作流、本仓库为 0.x 包定制的 semver 策略、changeset version/changeset publish的 CI 链路,以及仓库自建的 changeset 校验脚本如何把不合规的变更拦在合并之前。
一、.changeset/README.md 讲了什么:一个自动生成的管理目录
.changeset/README.md 是 @changesets/cli 在仓库初始化时自动生成的说明文件。它明确告诉开发者三件事:
.changeset/目录由@changesets/cli自动生成,该工具同时支持多包仓库(monorepo)和单包仓库(single-package repo)两种形态,用于帮助项目完成版本号(version)与发布(publish)流程;- Changesets 的完整文档托管在它自己的上游仓库中;
- 目录里收集了「常见问题」入口,供刚接触该流程的贡献者快速上手。
这段描述虽然简短,却是整个发布体系的地图。真正支撑它的,是仓库里一系列配套的实现:.changeset/config.json(全局配置)、一批真实存在的 changeset 文件(待发布变更记录)、根目录 package.json 中的 CI 脚本、以及 scripts/check-changesets.mjs 与 scripts/check-changeset-semver.mjs 两套自建校验。下面逐层展开。
二、仓库的 Changesets 全局配置:.changeset/config.json
仓库根目录的 .changeset/config.json 是 Changesets 的行为基准,当前内容如下:
{
"$schema": "https://unpkg.com/@changesets/config@3.0.1/schema.json",
"changelog": [
"@assistant-ui/x-changelog",
{
"repo": "assistant-ui/assistant-ui"
}
],
"access": "public",
"format": false,
"privatePackages": {
"version": false
},
"___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
"onlyUpdatePeerDependentsWhenOutOfRange": true
}
}
逐项解读:
| 配置项 | 当前值 | 含义与影响 |
|---|---|---|
$schema |
@changesets/config@3.0.1 的 schema |
配置的 JSON Schema 来源,编辑器可据此获得校验与补全;@changesets/cli 在根 package.json 中被声明为 ^3.0.3,两者版本对齐 |
changelog |
<a href="https://link.gitcode.com/i/c646e7f6ae63517bb72783f3d85b3316" target="_blank">"@assistant-ui/x-changelog", { "repo": "assistant-ui/assistant-ui" }] |
指定 changelog 生成器为仓库自研的 @assistant-ui/x-changelog,并传入 repo 参数;生成器实现在 [packages/x-changelog/index.mjs |
access |
"public" |
发布到 npm 时对所有包公开访问(即发布为公共包,而非受限于 npm 组织的私有包) |
format |
false |
关闭 changeset 文件的自动重排格式化,保留作者原始书写格式 |
privatePackages.version |
false |
私有包("private": true)不参与版本号提升,只有公开发布的包才会被 changeset version 处理 |
onlyUpdatePeerDependentsWhenOutOfRange |
true |
仅当依赖版本超出 peerDependencies 允许范围时才级联更新依赖方,减少不必要的连带 bump |
其中 changelog 是配置里最值得展开的一项。仓库自研的 @assistant-ui/x-changelog 是从 @changesets/changelog-github@1.0.0 fork 而来,核心差异只有一点:把作者署名从正文前的 " Thanks @user!" 挪到首行末尾的 " (@user)",使 changelog 首行更紧凑、便于扫描(见 packages/x-changelog/index.mjs 的注释)。它还实现了两个 changelog 钩子:
getReleaseLine(changeset, type, options):从 changeset 的 summary 中解析pr:、commit:、author:前缀,分别替换为 PR 链接、commit 链接和用户链接,并把#123这样的 issue 引用自动链接化(linkifyIssueRefs);getDependencyReleaseLine(changesets, dependenciesUpdated, options):当某个包的发布触发依赖方版本更新时,生成- Updated dependencies [...]段,逐行列出发布的依赖名与新版本号(dependency.name@dependency.newVersion)。
注意:x-changelog 的 getReleaseLine 在缺少 repo 配置时会直接抛错,因此 .changeset/config.json 中必须成对提供 repo 参数,这是该生成器的硬性要求。
三、changeset 文件长什么样:仓库里的真实样本
.changeset/ 目录下除 README 与 config.json 外,还存放着一批待发布的 changeset 文件(当前仓库中如 bright-ducks-sort.md、cloud-run-auth-generation.md、puny-pugs-fetch.md 等)。一个合法的 changeset 是 Markdown 文件,由两部分组成:
- YAML frontmatter:以
---分隔,列出「包名: 升级类型」映射; - 正文:人类可读的变更摘要,最终会被写入对应包的 CHANGELOG.md。
仓库中的真实样本(.changeset/persist-seeded-history.md):
---
"@assistant-ui/core": patch
---
fix(core): preserve initial messages after an empty history load and persist them before the first new message
再看一个多包共用一个 changeset 的样本(.changeset/quiet-crabs-send.md):
---
"@assistant-ui/core": patch
"@assistant-ui/react": patch
"@assistant-ui/vue": patch
---
Block typing, attachments, sends, and message editing while a thread is disabled.
frontmatter 中的升级类型只有三个合法取值:patch、minor、major(另有一个内部使用的 none)。包名必须与 pnpm-workspace.yaml 声明的 workspace 包名完全一致。正文推荐带 fix(...) / feat(...) 这类约定式提交前缀,便于 changelog 阅读与检索。
3.1 校验脚本对文件格式的严格要求
仓库在 scripts/lib/changesets.mjs 中实现了对上述格式的严格解析,CI 无法解析的 changeset 会被直接拒绝:
- frontmatter 边界:必须匹配
/^\s*---(<a href="https://link.gitcode.com/i/9b7407f042cf3b2fabbe2ca8c23b8e68" target="_blank">\s\S]*?)\r?\n\s*---(\s*(?:\n|$)[\s\S]*)/,即开头的---与结尾的---之间是 YAML 块(readChangesetSource,[scripts/lib/changesets.mjs); - 行格式:每条「包名: 类型」必须是 YAML block-mapping 行——包名不能以 YAML 指示符开头(也不能是
-/?开头的序列/复杂键),冒号后必须有空格或 Tab,且缩进只能用空格(用 Tab 缩进会被判为非法,见parseReleaseLine的正则,scripts/lib/changesets.mjs); - 包名唯一:同一个 changeset 里一个包只能出现一次,重复命名会报错(
readChangesetReleases,scripts/lib/changesets.mjs); - 缩进一致:同一 changeset 内所有 release 行的缩进必须一致,否则视为错误。
从这些校验细节可以看出:虽然 changeset 只是"Markdown + YAML",但为了与 @changesets/parse 的行为严格对齐,仓库在 CI 里不依赖 node_modules 就完成了等价解析(文件头注释明确说明这是 mdRegex 的拷贝,scripts/lib/changesets.mjs)。
四、实战工作流:从 pnpm changeset 到发布
4.1 创建 changeset
在 assistant-ui 仓库根目录执行:
pnpm changeset
@changesets/cli 会检测自上次发布以来哪些包发生了变更,并交互式地引导你完成三件事:
- 选择要发布的包(支持多选,一次性可为一个以上包记录变更);
- 选择升级类型(
patch/minor/major); - 填写变更描述。
完成后会在 .changeset/ 下生成一个新的随机命名(如 bright-ducks-sort.md)Markdown 文件,格式与第三节的样本一致,之后把它随代码一起提交。
4.2 提交规范与 CI 强制校验
仓库 CONTRIBUTING.md 明确:每个改了发布包的 PR 都必须附带 changeset,否则变更不会发布到 npm。这条规则由两套自建脚本强制落地(定义于根 package.json):
changesets:check→node scripts/check-changesets.mjs:扫描.changeset/下所有.md文件(跳过README.md),报告「changeset version无法解析的文件」以及「命名了不可发布包」的问题。所谓不可发布包包括:不存在的 workspace 包(拼错或改名)、私有包(private: true且privatePackages.version: false)、与已发布包混在同一条 changeset 中的ignore包、没有 version 字段却与已发布包共存的包(见findUnreleasablePackages,scripts/check-changesets.mjs)。任一类错误都会令脚本以非零状态退出;changeset-semver:check→node scripts/check-changeset-semver.mjs:为 0.x 包定制 semver 门槛,防止破坏依赖范围的 bump 进入发布流程。
4.3 一键版本化与发布
变更合并到 main 后,CI 看到 .changeset/ 中有待处理变更,会自动创建 "update versions" PR,其中执行:
changeset version && pnpm install --no-frozen-lockfile --lockfile-only
即根 package.json 中的 ci:version 脚本。changeset version 会完成三件事:消费掉 .changeset/*.md(删除已处理的 changeset 文件)、按 frontmatter 声明的类型提升各包 package.json 的 version 字段、用 x-changelog 生成器重写各包 CHANGELOG.md。随后 pnpm install --lockfile-only 同步 lockfile,保证版本号变更反映到 pnpm-lock.yaml。
该 PR 合并后,CI 执行发布脚本(package.json):
turbo build --filter="./packages/*" && changeset publish
先用 turbo 并行构建 packages/ 下所有包,再调用 changeset publish 把本次 release 涉及的包逐一发布到 npm(配合配置中的 "access": "public")。
4.4 变更包校验:--changed-packages 模式
check-changesets.mjs 还支持按提交范围校验:
node scripts/check-changesets.mjs --changed-packages
该模式要求设置 BASE_SHA 与 HEAD_SHA 环境变量,然后通过 git diff 找出 fork point 与 head 之间改动的文件,判定「改了发布包却没有对应 changeset」的 PR 并直接失败(见 runChangedPackageCheck 与 mainChangedPackages,scripts/check-changesets.mjs)。其判定规则值得一提:
- 包内
package.json、dist/、测试目录、测试文件、顶层 Markdown 的改动不计入「需要 changeset」; - 但
package.json中影响消费者安装的字段(如exports、files、bin、sideEffects、engines、publishConfig、peerDependenciesMeta、安装钩子、第三方依赖范围等)一旦变化,就需要 changeset 点名该包; - 反之,纯
versionbump、devDependencies修改、消费者不会运行的scripts条目、以及 workspace 依赖的范围调整(仅改范围不改名字)都由 release 流程自行处理,无需贡献者写 changeset。
五、0.x 时代的 semver 策略:为什么"几乎永远选 patch"
assistant-ui 的大多数包仍处于 0.x 版本(如 0.12.15)。在 semver 中,caret 范围 ^ 对 0.x 的处理与 1.x+ 完全不同:
| 范围 | 允许的升级 | 示例 |
|---|---|---|
^1.3.12 |
任意 minor 或 patch(>=1.3.12 <2.0.0) |
1.4.0 可以 |
^0.12.15 |
仅 patch(>=0.12.15 <0.13.0) |
0.13.0 超出范围 |
也就是说,对 0.x 包做一次 minor bump,会立刻破坏所有依赖它的包的 caret 范围,迫使 changesets 沿整个依赖图级联产生 patch bump,造成无意义的版本波动和噪音 changelog。
因此仓库的 CONTRIBUTING.md 定下了三条硬规则:
- patch:所有变更都选它——bug 修复、新功能、重构、新导出,一律 patch;
- minor:仅当维护者明确要求时使用(会在整个依赖图上引发级联 patch bump);
- major:仅用于计划内的稳定版本(
1.0、2.0),未经维护者批准绝不使用。
这也解释了为什么第三节列出的仓库现存 changeset 清一色是 patch——这不是巧合,而是既定策略的执行结果。
六、边界情况:什么不需要 changeset
并非所有仓库内容变更都走 changeset,以下几点是常见的边界:
- 不发布到 npm 的包:如
@assistant-ui/docs、@assistant-ui/shadcn-registry这类部署在 Vercel 的应用/注册表包,无需 changeset; - Python 包:
python/目录下的包不写 changeset,它们的pyproject.toml版本号由维护者在发布 PR 中、发布到 PyPI 前统一提升(check-changeset-semver.mjs还会拦截"与其它包改动混在一起"的pyproject.toml版本修改); - 纯测试与顶层文档:测试文件和顶层 Markdown 的改动不计入需要 changeset 的范围。
七、写给贡献者的快速上手指南
结合以上内容,在 assistant-ui 提交一个会被发布的改动时,完整流程是:
- 实现改动并写测试,在本地
pnpm changeset生成 changeset,类型优先选patch; - 提交代码与 changeset 文件,推送到 PR;
- CI 依次跑
changesets:check与changeset-semver:check:前者校验文件可解析、包名真实且可发布,后者校验 0.x 包的 bump 级别合法,任一失败 PR 即被拦截; - 合并到
main后,CI 自动开出 "update versions" PR(changeset version+ lockfile 同步),合入后turbo build+changeset publish将新版本发布到 npm,同时各包CHANGELOG.md由@assistant-ui/x-changelog写入带 PR/commit/作者链接的条目。
整个过程从 .changeset/README.md 里短短三句话开始,背后是配置、格式校验、semver 策略、CI 脚本与自研 changelog 生成器共同组成的一条完整发布链路——理解这条链路,就能在仓库里放心地提交任何会被发布到 npm 的改动。