This document describes how we use Changesets in our daily development workflow to manage versions, changelogs, and releases in this monorepo.

A changeset is a small Markdown file committed alongside your code changes. It records:

• Which packages are affected
• What type of version bump they require (patch, minor, major)
• A short description that will appear in the changelog

By collecting these small pieces of information, we can automatically generate:

• Version bumps in package.json
• Updated CHANGELOG.md entries
• Release PRs and npm publishes
• GitHub Releases

Run:

npx changeset

You’ll be prompted to:

• Select affected packages
• Choose the bump/release type (patch, minor, major)
• Provide a short summary for the changelog

This creates a file like .changeset/abcd123.md. 👉 Commit this file as part of your PR.

• Every PR that changes published code must include a changeset file.
• CI will verify the existence of at least one changeset when necessary.

When PRs are merged into main branch, the Release workflow will:

• Collect pending changesets
• Open (or update) a Release PR called “Version Packages”
• Run changeset version to bump versions and update changelogs

This PR should be reviewed like any other:

• Check the versions are correct
• Review the generated changelogs

Once everything looks good, merge the Release PR.

After the Release PR is merged into main branch:

• CI will build the packages (./build-outputs/)
• Publish new versions to npm with the tag latest
• Create a GitHub Release

You don’t have to run anything manually, it’s handled by CI.

• Always add a changeset

  If your code change affects published packages, create a changeset.

  No changeset → no version bump → no release.

• Choose the correct bump type

  • patch: bugfix, no API or HTML changes
  • minor: new features, changes in inner component markup or behavior, backwards-compatible
  • major: breaking changes (e.g. removed props, changed APIs)

• Write user-friendly summaries

  The text you provide will be copied into the CHANGELOG.md. Keep it concise and helpful.

• One changeset per PR

  Usually you only need one. If a PR touches multiple packages with different bump types, a single changeset can cover them all.

• Baseline snapshots

  ARIA snapshots by Playwright help detect markup changes. If they change, prefer minor instead of patch. And please mention those HTML changes within the CHANGELOG.md or of necessary (like bigger changes) in a migration guide.

• Avoid manual version bumps

  Never edit package.json version field by hand. Changesets handles this automatically.

We handle pre-releases without changesets. Instead, create a new GitHub release with a tag like 1.2.3-next0 and the CI will pick it up and publish it to npm with the tag next.

# Initialize Changesets (only once per repo)
npx changeset init

# Create a new changeset
npx changeset

# Show pending releases
npx changeset status --verbose

# Apply version bumps and changelogs
npx changeset version

# Pre-release mode
npx changeset pre enter next # enter prerelease
npx changeset pre exit # exit prerelease

• .changeset/ → contains pending changesets (.md files)
• package.json → versions are updated automatically in this file
• CHANGELOG.md → updated by changeset version
• .github/workflows/changesets-release-pr.yml → automation for Release PRs & publishing
• .github/workflows/pull-request-snapshot-diff.yml → validates changes in PNG/YML snapshots and enforces at least a MINOR bump
• scripts/github/publish-npm.js → custom publish script (packs & publishes built outputs)