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.

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

Critical Rules

1. Core packages: no minor

Forbidden: minor changesets for:

• @platejs/slate
• @platejs/core
• platejs

Use patch instead. minor on those explodes version bumps across dependents.

# Wrong
---
"@platejs/core": minor
---

# Correct
---
"@platejs/core": patch
---

Only real breaking changes get major.

2. One package per file

Never combine packages in one changeset.

# Wrong
---
'@platejs/core': patch
'@platejs/utils': patch
---

# Correct
.changeset/core-fix-types.md
.changeset/utils-add-helper.md

3. Registry work is changelog work

If changes are only under apps/www/src/registry/, do not write a package changeset.

Update docs/components/changelog.mdx instead.

4. Style

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:

- Fix `asChild` TypeScript error
- Add `disabled` prop to Button

Use code examples only when needed:

// Before
editor.api.foo();

// After
editor.tf.foo();

Focus on user impact only. No implementation diary.

Template

Simple:

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

Fix `isEmpty` not handling void elements correctly

API change:

---
"@platejs/core": patch
---

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

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

// After
editor.tf.foo();
```

Breaking change:

---
'@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' } },
});
```

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

Registry Changelog Format

For apps/www/src/registry changes:

### [Month Day] #[Version]
- **`component-name`**: Brief description
  - Migration note if actually needed

Same style rules: concise, imperative, user impact only.