changeset

Changeset 是 udecode/plate 项目中的一项技能，用于为软件包变更编写发布说明文件（.changeset/*.md）。其核心原则是：一个动作动词 + 一条影响说明 = 一条要点。

用途

该技能用于：

创建 .changeset/*.md 文件
记录软件包变更：feat、fix、breaking
为复制的注册表组件更新 Plate UI 注册表变更日志源

不适用于：

内部文档
提交信息
PR 描述

主要能力与关键规则

核心包禁止使用 minor 对于 @platejs/slate、@platejs/core、platejs，禁止使用 minor changeset，应改用 patch。对这些包使用 minor 会导致依赖项的版本号大幅膨胀。只有真正的破坏性变更才使用 major。
每个文件只写一个包绝不在一个 changeset 中合并多个包。
始终相对于 main，而非最后一次提交绝不相对于最后一次提交、暂存差异、当前工作树、分支本地计划或刚做的更改来编写 changeset。在创建或编辑 changeset 前，需回答一个问题：从当前 main 升级的用户会观察到什么？使用 main / origin/main 作为发布基线。如果某个符号、选项、行为、文件或 bug 仅存在于当前分支且从未在 main 上存在，则不要为其编写移除、迁移或破坏性 changeset。相反，只描述相对于 main 的最终用户可见差异，或者如果没有已发布的包差异，则不写 changeset。

这意味着：

描述从 main 升级的用户需要知道的内容
仅当用户实际需要执行操作时才描述迁移步骤
优先描述 API 形态、运行时行为、序列化数据形态或配置变更
在编写移除或迁移说明前，检查所提及的已移除/重命名的 API 是否确实存在于 main 上

不要写：

针对同一分支上引入并删除的 API 的、相对于最后一次提交的移除说明
实现日记
架构理由
内部所有权或接缝语言
测试覆盖说明
“editor-owned”、“normalize path”、“wrap semantics” 或类似内部措辞，除非公共 API 字面上使用这些词

如果某个包在此分支上内部发生了变化，但相对于 main 没有用户可见差异，则不要为该包编写 changeset。

注册表工作属于注册表变更日志工作如果更改仅位于 apps/www/src/registry/ 下，则不要编写包 changeset。应改用 registry-changelog 技能。它负责源条目模式、脚手架命令、生成器命令和验证检查：

node tooling/scripts/generate-ui-changelog-entries.mjs --new <id> --summary "<summary>" --items <item-a,item-b> --kind <kind> node tooling/scripts/generate-ui-changelog-entries.mjs --write node tooling/scripts/generate-ui-changelog-entries.mjs --check

sync-plate-ui 用于消费生成的 JSON 的下游用户应用。不要用它来生成上游 Plate 变更日志条目。

风格使用祈使语气：

Add support for X
Fix Y behavior
Remove deprecated Z

不要使用：

Added ...
We fixed ...

简单更改保持一行：

Fix asChild TypeScript error
Add disabled prop to Button

仅在需要时使用代码示例：

// Before editor.api.foo();

// After editor.tf.foo();

仅关注用户影响。不要写实现日记。

优先采用以下形态：

一句摘要
可选的简短 Migration: 块
仅在迁移含义不明确时，可选的 before/after 示例

如果一句话在发布说明中听起来很蠢，就删掉它。

模板

简单：

"@platejs/utils": patch

Fix isEmpty not handling void elements correctly

API 变更：

"@platejs/core": patch

Rename editor.api.foo to editor.tf.foo

// Before
editor.api.foo();

// After
editor.tf.foo();

破坏性变更：

'@platejs/basic-nodes': major

Remove SkipMarkPlugin; functionality is built into core

Migration: Remove SkipMarkPlugin from your plugin list. Configure marks directly:

MyMarkPlugin.configure({
  rules: { selection: { affinity: 'outward' } },
});

危险信号

发布前检查：

对 @platejs/slate、@platejs/core 或 platejs 使用了 minor？改为 patch
frontmatter 中有多个包？拆分文件
描述的是最后一次提交、工作树或仅分支内 API，而非相对于 main 的用户可见差异？重写
声称某个 API 已被移除或需要迁移，但未证明该 API 存在于 main 上？删除该声明
使用了过去时动词？修正
有多个段落？精简
解释过多？删减
API 变更没有 before/after？添加一个

注册表变更日志

对于 apps/www/src/registry 的更改，使用 registry-changelog 技能。不要在此重复其模式。