Changeset & Release Manager

Purpose

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?
• Changeset Types
• Decision Guide
• Creating a Changeset
• Release Workflow
• Checking Status
• References

What is a Changeset?

.changeset/

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

Changeset Types

patch

minor

major

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

1. Select affected packages (space to select)
2. Choose bump type for each package
3. Write a summary of changes

Manual Method

.changeset/

---
"@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

• Bug fixes, new features, breaking changes
• Multiple related changes
• Consolidated changesets
• Pre-release versions
• Best practices for descriptions

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