Commit-message versioning infers what a change means from how it was described. Changesets take the opposite approach: contributors write a small file stating which packages their change affects and whether each is a patch, minor, or major, along with a description for the changelog.
The information is the same. Stating it explicitly rather than inferring it turns out to matter in a monorepo.
What changed in 2026
- Monorepo adoption pushed explicit declaration. As repositories with many independently versioned packages became common, the ambiguity of inferring per-package impact from one commit message became a practical problem.
- Reviewability got recognized as the main benefit. Having the version claim visible in the pull request, next to the code, proved more valuable than the mechanics.
- Release pull requests became standard. Accumulating changesets and opening a single release pull request that applies them all became the common workflow.
- Dependent bumping matured. Automatic version bumps for packages depending on a changed package became reliable rather than a source of surprises.
Changesets versus commit parsing
|
Commit-based |
Changesets |
| Where intent is expressed |
Commit message |
A dedicated file |
| Per-package granularity in a monorepo |
Awkward |
Natural |
| Visible in code review |
Only as a message |
As a reviewable file |
| Contributor burden |
Follow a message convention |
Add a file |
| Missing declaration |
Version inferred, possibly wrong |
Change goes unreleased |
| Changelog text |
Derived from commit subject |
Written deliberately |
| Best for |
Single package, high commit discipline |
Monorepos, multiple packages |
The per-package row is the substantive difference. In a monorepo, a single pull request can be a breaking change for one package, a feature for another, and irrelevant to the rest. Expressing that in one commit message is awkward; expressing it in a file listing each package and its bump is straightforward.
The reviewability point is underrated. When a contributor declares a change as a patch and the reviewer can see it removes a public method, that conversation happens during review rather than after a consumer breaks.
The workflow
Contributors add a changeset file alongside their code changes. The file names the affected packages, the bump type for each, and a description.
Those files accumulate on the main branch as pull requests merge. Nothing is released yet.
A release process then collects the pending changesets, computes the resulting versions including bumps for dependent packages, updates changelogs, and opens a release pull request. Merging that pull request publishes.
That release pull request is a useful checkpoint. It shows exactly what will be published, at what versions, with what release notes, before anything is public — which is the publish gating that semantic release guide recommends adding to commit-based flows.
The main failure mode is a contributor forgetting the changeset. The fix is mechanical: a CI check that fails when a pull request touches package source without adding a changeset, with an explicit escape for changes that genuinely need no release.
Common mistakes
- No CI check for missing changesets. Changes merge and are never released.
- Using it for a single package. More ceremony than commit parsing for the same outcome.
- Writing changelog descriptions as commit subjects. The description is for users; write it for them.
- Ignoring dependent bumps. Packages depending on a changed one need releasing too; let the tooling handle it.
- Letting the release pull request go stale. Accumulated unreleased changes make each release larger and riskier.
FAQ
Can I use changesets with a single package?
Yes, and the benefit is smaller. Commit-based versioning is less friction for the same result.
What about changes that need no release?
Declare an empty changeset or configure the CI check to accept an explicit no-release marker, so intent is recorded either way.
Does it handle pre-release versions?
Yes, with a pre-release mode that versions accordingly until you exit it.
Can I combine both approaches?
Generally not usefully. Pick one source of truth for version intent, or they will disagree.
Where to go next
For the alternative, read semantic release guide. For the repository structure, monorepo tooling compared, and for review practice, pull request review culture.