--- name: changeset description: Write concise package-release changesets for monorepo publishing — one action verb + one impact statement per bullet, imperative voice, user-impact only. Use when creating a `.changeset/*.md` for a published package. --- # 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. ```yaml # 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. ```bash # 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: ```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. ## 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' } }, }); ``` ```` ## 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: ```md ### [Month Day] #[Version] - **`component-name`**: Brief description - Migration note if actually needed ``` Same style rules: concise, imperative, user impact only.