Changesets

pubm 将 changeset 作为“下一次应该发布什么”的持久记录。它不会根据提交信息或分支名推断版本，而是读取 .pubm/changesets/ 中已提交的文件，并将它们转换为版本变更和 changelog 条目。

为什么 changesets 重要

每个 pull request 中都能保留可审阅的发布计划
跨包的版本 bump 计算是确定性的
changelog 内容在发布日前就能写好，而不是发布后补写

文件位置

待处理的 changeset 位于：

.pubm/changesets/

运行交互式 setup 向导来初始化该目录：

pubm init

在 setup 过程中，pubm init 会询问是否启用 changesets 工作流。选择”是”会创建 .pubm/changesets/ 目录，生成 .github/workflows/changeset-check.yml 用于 PR 强制检查，并更新 .gitignore 以跟踪 changeset 文件，同时忽略其他 .pubm/ 内容。

创建 changeset

pubm changesets add

在 monorepo 中，pubm 还会询问受影响的包，以及每个包应该获得什么 bump 类型。

非交互式用法：

pubm changesets add \
  --packages @acme/core,@acme/react \
  --bump minor \
  --message "Add token-based auth to the public client."

changeset 文件包含什么

---
"@acme/core": minor
"@acme/react": patch
---

Add token-based auth to the public client.

元数据控制版本计算，正文会成为 changelog 摘要。

查看待处理变更

在消耗 changeset 之前，先检查它们：

pubm changesets status
pubm changesets status --verbose
pubm changesets version --dry-run

changeset 如何被消耗

当你用 pubm 运行正常发布流程时，待处理的 changeset 会在版本步骤中被消耗。

该流程会：

读取待处理的 .pubm/changesets/*.md 文件
计算最终的包版本
更新 manifest 版本
生成 changelog 条目
删除已消耗的 changeset 文件
创建发布提交和 tags

如果你只想提前执行版本计算部分，也可以运行：

pubm changesets version

这个命令适合编辑流程或受控流程，但在 pubm 或 pubm --mode ci --phase publish 之前并不是必需的。

生成 changelog

如果你想先生成 changelog 文本，而不消耗版本：

pubm changesets changelog --dry-run
pubm changesets changelog --version 1.8.0

Conventional commit 降级回退

当 versionSources 为 "all"（默认值）时，pubm changesets version 会对没有待处理 changeset 文件的包自动回退到 conventional commits。这使团队可以逐步采用 changeset：有 changeset 的包使用 changeset；没有 changeset 的包则回退到提交历史。

默认提交类型映射

提交类型	Bump
`feat`	`minor`
`fix`	`patch`
`perf`	`patch`

footer 中包含 BREAKING CHANGE，或使用 ! 后缀（如 feat!:），始终产生 major bump。

配置自定义映射

在 pubm.config.ts 中覆盖默认映射：

export default defineConfig({
  versionSources: "all",
  conventionalCommits: {
    types: {
      feat: "minor",
      fix: "patch",
      perf: "patch",
      docs: "patch",
    },
  },
});

设置 versionSources: "commits" 可仅使用 conventional commits，完全忽略 changeset 文件。设置 versionSources: "changesets" 可禁用回退，仅使用 changeset 文件。

从 `.changeset/` 迁移

pubm changesets migrate

这会把 .changeset/ 中的待处理文件迁移到 .pubm/。