Create Changesets

Overview

Generate changesets, update documentation, draft blog entries, and update skills for user-facing changes.

Steps

Analyze changes

• Compare current branch to master to identify modified packages

• Group changes by impact type (feature, fix, breaking)

• Identify transitive dependencies that expose the change

• Check for modified skills in .cursor/skills/ and packages/*/.cursor/skills/

Determine affected packages

• Include directly modified packages

• Add transitive dependents when interfaces/behaviors are exposed:

• @data-client/endpoint → also select @data-client/rest , @data-client/graphql

• @data-client/core or @data-client/normalizr → also select @data-client/react , @data-client/vue

Run changesets

• Run yarn changeset once per distinct change

• Select all affected packages (direct + transitive)

• Choose appropriate version bump (patch/minor/major)

• For packages under 1.0, use minor for breaking changes

Update documentation

• Update primary docs in docs/ for any changed public APIs

• Search for all usages of changed APIs across docs/ , packages/*/README.md , and root README.md

• Update all found references to reflect new behavior, signatures, or deprecations

• For new exports: add to relevant API reference pages

Update release blog

• Find the latest draft blog post in website/blog/ (has draft: true in frontmatter)

• Add the change following @website/blog/.cursor/rules/blog-posts.mdc :

• Place in appropriate conceptual category section

• Include code example if applicable

• Link to PR/commit and relevant docs

• For breaking changes: add to summary's Breaking Changes section with anchor link

Update skills

• If code changes affect workflows described in existing skills, update those skills to match

• If new APIs or patterns are introduced that agents should know about, add them to the relevant skill

• Skill changes don't need changesets — they are development tooling, not published packages

Changeset Format

• First line: Action verb ("Add", "Fix", "Update", "Remove")

• Breaking: Prefix with BREAKING CHANGE: or BREAKING:

• Body: 1–3 lines describing outcome, not implementation

• New exports: Use "New exports:" with bullet list

Code Examples in Changesets

• Fixes: // Before: ... ❌ // After: ... ✓

• Breaking changes: Use #### Before and #### After headers

• Multiple use cases: Separate with brief labels

Markdown Formatting

Follow @.cursor/rules/markdown-formatting.mdc for all markdown content.