creating-changesets

saleor's avatarfrom saleor

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.

⭐20stars🔀2forks📁View on GitHub🕐Updated Dec 15, 2025⬇️2downloads

When & Why to Use This Skill

This Claude skill automates the semantic versioning process and release note generation using Changesets. It helps developers accurately determine version bump types (patch, minor, or major), ensures well-documented changelog entries, and streamlines the entire release workflow. By integrating with tools like pnpm and git, it eliminates manual versioning errors and maintains a professional, automated delivery pipeline.

Use Cases

  • Automating Bug Fix Releases: Automatically generate patch-level changesets and descriptive changelog entries immediately after completing a bug fix.
  • Managing Breaking Changes: Identifying major API modifications and generating structured migration instructions and release notes for end-users.
  • Monorepo Version Coordination: Using pnpm changesets to manage and synchronize complex version bumps across multiple interdependent packages within a single repository.
  • Standardizing Team Workflows: Ensuring every Pull Request includes a properly formatted changeset to maintain a consistent and automated release history.
  • Release Preparation: Previewing version bumps and dry-running releases to ensure project metadata and changelogs are correct before deployment.
namecreating-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:

  1. Which packages are affected
  2. What type of version bump (patch/minor/major)
  3. 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:

  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

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

  • CI/CD automation: See managing-github-ci for release workflow integration
  • Pre-commit validation: See validating-pre-commit for quality gates before committing