creating-changesets

Changeset & Release Manager

Overview

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

What is a Changeset?

A changeset is a markdown file in the .changeset/ directory that describes:

1. Which packages are affected
2. What type of version bump (patch/minor/major)
3. A description of the change

Changeset Types

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:

1. Select affected packages (space to select)
2. Choose bump type for each package
3. 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

# See what changesets exist
npx changeset status

# Preview version bump
npx changeset version --dry-run

Common Mistakes

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

• {baseDir}/.changeset/config.json - Changeset configuration
• {baseDir}/CHANGELOG.md - Generated changelog
• Changesets docs: https://github.com/changesets/changesets

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