| name | creating-changesets |
| description | Creates changesets for semantic versioning and automates release notes. Determines correct version bump type (patch/minor/major) and generates well-documented changelog entries. Triggers on: add changeset, create changeset, version bump, prepare release, CHANGELOG, breaking change, pnpm changeset. |
| allowed-tools | Read, Grep, Glob, Write, Edit, Bash(git:*), Bash(npx changeset:*) |
Changeset & Release Manager
Purpose
Automate the creation of changesets following project conventions, ensuring proper version bumps and well-documented release notes.
When to Use
- After completing a feature or fix
- Before creating a PR
- When preparing a release
- To document breaking changes
Table of Contents
What is a Changeset?
A changeset is a markdown file in the .changeset/ directory that describes:
- Which packages are affected
- What type of version bump (patch/minor/major)
- A description of the change
Changeset Types
| Type | When to Use | Version Change |
|---|
patch | Bug fixes, documentation, refactoring, dependency updates | 1.0.0 → 1.0.1 |
minor | New features, non-breaking enhancements | 1.0.0 → 1.1.0 |
major | Breaking changes, API modifications | 1.0.0 → 2.0.0 |
Decision Guide
Use patch for:
- Bug fixes that don't change behavior
- Documentation updates
- Internal refactoring (no API changes)
- Dependency updates (non-breaking)
- Performance improvements
- Code style/linting fixes
Use minor for:
- New features
- New CLI commands
- New configuration options
- Enhanced functionality
- New entity types support
- Non-breaking API additions
Use major for:
- Breaking configuration changes
- Removed features or commands
- Changed CLI interface
- Required migration steps
- Node.js version requirement changes
Creating a Changeset
Interactive Method
pnpm changeset
Follow the prompts:
- Select affected packages (space to select)
- Choose bump type for each package
- Write a summary of changes
Manual Method
Create a file in .changeset/ with a random name:
---
"@saleor/configurator": minor
---
Add support for reference attributes with entityType field
- Attributes of type REFERENCE now require an entityType field
- Introspection properly captures entity type references
- Deploy correctly handles reference attribute creation
File Format
---
"package-name": patch|minor|major
---
Short description of the change (shown in CHANGELOG)
Optional longer description with:
- Bullet points for details
- Code examples if needed
- Migration instructions for breaking changes
Release Workflow
1. Create Changeset
pnpm changeset
git add .changeset/
git commit -m "chore: add changeset for feature"
2. PR and Review
- Changeset is part of the PR
- Reviewers can suggest bump type changes
3. Merge to Main
- Changesets action creates "Version Packages" PR
- This PR updates version and CHANGELOG
4. Merge Version PR
- Triggers npm publish
- Creates GitHub release
Checking Status
npx changeset status
npx changeset version --dry-run
Common Mistakes
| Mistake | Issue | Fix |
|---|
| Wrong bump type | Unexpected version | Review decision guide above |
| Vague description | Poor CHANGELOG | Be specific about changes |
| Missing changeset | No release notes | Always add before PR |
| Multiple changesets | Fragmented notes | Combine related changes |
| Not including context | Hard to understand | Explain why not just what |
Common Scenarios
For detailed examples of common scenarios including:
- Bug fixes, new features, breaking changes
- Multiple related changes
- Consolidated changesets
- Pre-release versions
- Best practices for descriptions
See Scenarios & Examples
References
Related Skills
- CI/CD automation: See
managing-github-ci for release workflow integration
- Pre-commit validation: See
validating-pre-commit for quality gates before committing
