Changesets

pubm uses changesets as the checked-in record of what should be released next. Instead of inferring versions from commit messages or branch names, it reads files from .pubm/changesets/ and turns them into version bumps and changelog entries.

Why changesets matter

• a reviewable release plan in each pull request
• deterministic version bump calculation across packages
• changelog content written before release day, not after it

File location

Pending changesets live in:

.pubm/changesets/

Initialize that directory by running the interactive setup wizard:

pubm init

During setup, pubm init asks whether to enable the changesets workflow. If you choose yes, it creates the .pubm/changesets/ directory, generates .github/workflows/changeset-check.yml for PR enforcement, and updates .gitignore so changeset files are tracked while other .pubm/ contents stay ignored.

Creating a changeset

pubm changesets add

In a monorepo, pubm also asks which packages are affected and what bump type each one should receive.

For non-interactive use:

pubm changesets add \
  --packages @acme/core,@acme/react \
  --bump minor \
  --message "Add token-based auth to the public client."

What a changeset file contains

---
"@acme/core": minor
"@acme/react": patch
---

Add token-based auth to the public client.

The metadata controls version calculation. The body becomes the changelog summary.

Inspecting pending changes

Inspect changesets before pubm consumes them:

pubm changesets status
pubm changesets status --verbose
pubm changesets version --dry-run

How changesets are consumed

When you run the normal release pipeline with pubm, pending changesets are consumed during the version step.

The flow is:

1. reads pending .pubm/changesets/*.md files
2. calculates the resulting package versions
3. updates manifest versions
4. generates changelog entries
5. deletes consumed changeset files
6. creates the release commit and tags

If you want to run only the versioning step ahead of time, you can still use:

pubm changesets version

That command is useful for editorial or controlled workflows, but it is not required before pubm or pubm --mode ci --phase publish.

Changelog generation

If you want to generate changelog text without consuming versions yet:

pubm changesets changelog --dry-run
pubm changesets changelog --version 1.8.0

Conventional commit fallback

When versionSources is "all" (the default), pubm changesets version automatically falls back to conventional commits for any package that has no pending changeset files. This lets teams adopt changesets incrementally: packages with changesets use them; packages without fall back to commit history.

Default commit type mapping

Commit type	Bump
feat	minor
fix	patch
perf	patch

A BREAKING CHANGE footer or a ! suffix (e.g. feat!:) always produces a major bump.

Configuring custom mappings

Override the default mapping in pubm.config.ts:

export default defineConfig({
  versionSources: "all",
  conventionalCommits: {
    types: {
      feat: "minor",
      fix: "patch",
      perf: "patch",
      docs: "patch",
    },
  },
});

Set versionSources: "commits" to use only conventional commits and ignore changeset files entirely. Set versionSources: "changesets" to disable the fallback and use only changeset files.

Migration from .changeset/

pubm changesets migrate

This migrates pending files from .changeset/ into .pubm/.