Create Changesets

Overview

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

Steps

1. 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/

2. 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

3. 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

4. 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

5. 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

6. 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.