Back to Details

changeset

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Changeset

Changeset

Changesets document package changes for release. Concise bullets, imperative voice, user impact only.
Core principle: one action verb + one impact statement = one bullet.
Changeset 用于记录包发布的变更内容。需使用简洁的项目符号，祈使语气，仅关注用户影响。
核心原则：一个动作动词 + 一个影响说明 = 一个项目符号。

When To Use

适用场景

Use when:
  • Creating 
    .changeset/*.md
    files
  • Documenting package changes: feat, fix, breaking
  • Updating 
    docs/components/changelog.mdx
    for registry work
Do not use for:
  • Internal docs
  • Commit messages
  • PR descriptions
适用于：
  • 创建
    .changeset/*.md
    文件时
  • 记录包的变更：feat（新功能）、fix（修复）、breaking（破坏性变更）
  • 为注册表工作更新
    docs/components/changelog.mdx
不适用于：
  • 内部文档
  • 提交信息
  • PR描述

Critical Rules

关键规则

1. Core packages: no 
minor

1. 核心包：禁止使用
minor

Forbidden: 
minor
changesets for:
  • @platejs/slate
  • @platejs/core
  • platejs
Use 
patch
instead. 
minor
on those explodes version bumps across dependents.
yaml
undefined
禁止：为以下包创建
minor
变更集：
  • @platejs/slate
  • @platejs/core
  • platejs
请改用
patch
。对这些包使用
minor
会导致依赖包的版本大幅升级。
yaml
undefined

Wrong

错误写法

"@platejs/core": minor

"@platejs/core": minor

Correct

正确写法

"@platejs/core": patch


Only real breaking changes get `major`.

"@platejs/core": patch


只有真正的破坏性变更才能使用`major`。

2. One package per file

2. 每个文件对应一个包

Never combine packages in one changeset.
bash
undefined
切勿在一个变更集中合并多个包。
bash
undefined

Wrong

错误写法

'@platejs/core': patch '@platejs/utils': patch

'@platejs/core': patch '@platejs/utils': patch

Correct

正确写法

.changeset/core-fix-types.md .changeset/utils-add-helper.md
undefined
.changeset/core-fix-types.md .changeset/utils-add-helper.md
undefined

3. Registry work is changelog work

3. 注册表工作对应变更日志工作

If changes are only under 
apps/www/src/registry/
, do not write a package changeset.
Update 
docs/components/changelog.mdx
instead.
如果变更仅涉及
apps/www/src/registry/
目录，请不要编写包变更集。
请改为更新
docs/components/changelog.mdx
。

4. Style

4. 格式规范

Use imperative voice:
  • Add support for X
  • Fix Y behavior
  • Remove deprecated Z
Do not use:
  • Added ...
  • We fixed ...
Keep simple changes to one line:
md
- Fix `asChild` TypeScript error
- Add `disabled` prop to Button
Use code examples only when needed:
tsx
// Before
editor.api.foo();

// After
editor.tf.foo();
Focus on user impact only. No implementation diary.
使用祈使语气：
  • Add support for X
    （添加对X的支持）
  • Fix Y behavior
    （修复Y的行为）
  • Remove deprecated Z
    （移除已废弃的Z）
请勿使用：
  • Added ...
    （已添加……）
  • We fixed ...
    （我们修复了……）
简单变更保持为一行：
md
- Fix `asChild` TypeScript error（修复`asChild`的TypeScript错误）
- Add `disabled` prop to Button（为Button添加`disabled`属性）
仅在必要时使用代码示例：
tsx
// 之前
editor.api.foo();

// 之后
editor.tf.foo();
仅关注用户影响，不要记录实现细节。

Template

模板

Simple:
md
---
"@platejs/utils": patch
---

Fix `isEmpty` not handling void elements correctly
API change:
md
---
"@platejs/core": patch
---

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

```tsx
// Before
editor.api.foo();

// After
editor.tf.foo();
```
Breaking change:
md
---
'@platejs/basic-nodes': major
---

Remove `SkipMarkPlugin`; functionality is built into core

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

```tsx
MyMarkPlugin.configure({
  rules: { selection: { affinity: 'outward' } },
});
```
简单模板：
md
---
"@platejs/utils": patch
---

Fix `isEmpty` not handling void elements correctly（修复`isEmpty`无法正确处理空元素的问题）
API变更模板：
md
---
"@platejs/core": patch
---

Rename `editor.api.foo` to `editor.tf.foo`（将`editor.api.foo`重命名为`editor.tf.foo`）

```tsx
// 之前
editor.api.foo();

// 之后
editor.tf.foo();
```
破坏性变更模板：
md
---
'@platejs/basic-nodes': major
---

Remove `SkipMarkPlugin`; functionality is built into core（移除`SkipMarkPlugin`；相关功能已集成至核心包）

**迁移说明**：从插件列表中移除`SkipMarkPlugin`。直接配置标记：

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

Red Flags

注意事项

Before shipping:
  • Used 
    minor
    for 
    @platejs/slate
    , 
    @platejs/core
    , or 
    platejs
    ? Change to 
    patch
  • Multiple packages in frontmatter? Split files
  • Past tense verbs? Fix them
  • Multiple paragraphs? Condense
  • Too much explanation? Cut it
  • API change without before/after? Add one
发布前检查：
  • 是否为
    @platejs/slate
    、
    @platejs/core
    或
    platejs
    使用了
    minor
    ？请改为
    patch
  • 前置元数据中包含多个包？拆分文件
  • 使用了过去式动词？修正为祈使语气
  • 包含多个段落？精简内容
  • 解释过于冗长？删减不必要部分
  • API变更未提供前后对比？补充对比示例

Registry Changelog Format

注册表变更日志格式

For 
apps/www/src/registry
changes:
md
undefined
针对
apps/www/src/registry
的变更：
md
undefined

[Month Day] #[Version]

[月 日] #[版本号]

  • component-name
    : Brief description
    • Migration note if actually needed

Same style rules: concise, imperative, user impact only.
  • component-name
    ：简要描述
    • 如需迁移则添加迁移说明

遵循相同的格式规则：简洁、祈使语气、仅关注用户影响。