Version Packages with Changesets

Have contributors add a changeset describing the change, let CI open a version PR that bumps packages and updates the changelog, then publish on merge.

~40 minmonoreporeleaseci

Task

Adopt Changesets to version and release a monorepo predictably.

When to use this

Package versions and changelogs are edited by hand at release time, so versions drift, changelogs are incomplete, and publishing is stressful.

Prerequisites

A monorepo using a package manager
CI with permission to open pull requests

Steps

1. Require a changeset in pull requests that change published packages.

Expected output: The intent of each change is captured with it.

2. Let the version command consume changesets into version bumps and changelog entries.

Expected output: Versions and changelogs update consistently.

3. Open a version pull request in CI and publish on merge.

Expected output: Releases are reviewable and automated.

4. Verify the published package version matches the changeset intent.

npx changeset status --since=origin/main

Expected output: Release output is confirmed.

Troubleshooting

Problem

Forgotten changeset

Solution

Add a CI check that requires a changeset or an explicit skip note for package changes.

Problem

Wrong bump level

Solution

Review the version PR; the changeset intent determines major, minor, or patch and must be right before merge.

Limitations

Changesets works best with a clear package graph; unpublished or private packages need configuration.
It does not replace semantic versioning judgment; choosing the bump level is still a human decision.

Context

Adopt Changesets to version and release a monorepo predictably. Package versions and changelogs are edited by hand at release time, so versions drift, changelogs are incomplete, and publishing is stressful.

Steps

Require a changeset in pull requests that change published packages. Expected: The intent of each change is captured with it.
Let the version command consume changesets into version bumps and changelog entries. Expected: Versions and changelogs update consistently.
Open a version pull request in CI and publish on merge. Expected: Releases are reviewable and automated.
Verify the published package version matches the changeset intent. Expected: Release output is confirmed.

npx changeset              # add a changeset interactively
npx changeset version      # consume into bumps + changelog
npx changeset publish      # publish changed packages

Verify

The intent of each change is captured with it.
Versions and changelogs update consistently.
Releases are reviewable and automated.
Release output is confirmed.

Limits

Changesets works best with a clear package graph; unpublished or private packages need configuration.
It does not replace semantic versioning judgment; choosing the bump level is still a human decision.