/shared-tooling-changesets

name: shared-tooling-changesets
description: Versioning and changelog management with @changesets/cli — adding changesets, version bumping, changelog generation, monorepo publishing, pre-release modes, and CI automation

Changesets

> **Quick Guide:** Changesets decouple the _intent to release_ from the _act of publishing_. Contributors add a changeset file (YAML frontmatter + markdown summary) alongside their code. When ready to release, `changeset version` consumes all pending changesets to bump versions and write changelogs. `changeset publish` publishes to npm. Use `fixed` for packages that must always share a version, `linked` for packages that share versions only when changed, and `pre enter <tag>` for pre-release cycles.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST add a changeset via `changeset` or `changeset add` for every user-facing change -- documentation-only or CI-only changes use `changeset --empty`)**

**(You MUST run `changeset version` before `changeset publish` -- version consumes changesets and bumps package.json, publish reads the bumped versions)**

**(You MUST set `"access": "public"` in `.changeset/config.json` for public npm packages -- the default `"restricted"` prevents public publishing)**

**(You MUST run pre-releases from a feature branch, NOT the default branch -- pre-release mode blocks normal releases until exited)**

</critical_requirements>

---

**Auto-detection:** changesets, @changesets/cli, changeset add, changeset version, changeset publish, changeset status, changeset pre, changeset init, .changeset/config.json, changeset snapshot, CHANGELOG.md generation, semver bump, version packages

**When to use:**

• Managing package versioning and changelogs for single or multi-package repos
• Automating release workflows (version bumping, changelog generation, npm publishing)
• Coordinating releases across monorepo packages (fixed or linked versioning)
• Running pre-release cycles (alpha, beta, rc)
• Publishing snapshot/canary versions for testing

**When NOT to use:**

• Projects using conventional-commits-based versioning (different paradigm)
• Single-file scripts or internal tools that are never published
• Projects with no semver versioning needs

**Key patterns covered:**

• Changeset file format (YAML frontmatter + markdown body)
• Config options: `access`, `baseBranch`, `fixed`, `linked`, `commit`, `changelog`
• CLI commands: `changeset`, `version`, `publish`, `status`, `pre`, `tag`, `init`
• Monorepo strategies: fixed packages vs linked packages
• Pre-release workflow: `pre enter`, version, publish, `pre exit`
• Snapshot releases for testing without version bumps
• CI automation with status checks and release workflows

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Changeset files, config, versioning, publishing, monorepo strategies
• [examples/ci.md](examples/ci.md) - CI automation, status checks, pre-release, snapshots
• [reference.md](reference.md) - CLI command reference, config option reference, official doc links

---

<philosophy>

Philosophy

Changesets flip the release model: **contributors decide the version impact at PR time, not at release time**. A changeset is a small markdown file that declares which packages are affected, what semver bump they need, and a human-readable summary. This distributes versioning decisions to the people who understand the change best.

The workflow has three stages:

1. **Add** -- contributors create changeset files alongside their code changes 2. **Version** -- maintainers (or CI) consume all pending changesets to bump `package.json` versions and write `CHANGELOG.md` entries 3. **Publish** -- packages are published to npm with the new versions

**Key mental model:** A changeset is an _intent to release_, not a release itself. Multiple changesets accumulate between releases. When `changeset version` runs, it combines all pending intents into the minimal set of version bumps.

**When to use Changesets:**

• Any npm package (single or monorepo) that follows semver
• Teams where multiple contributors need to declare version impacts independently
• Projects that want changelogs generated from structured data, not commit messages

**When NOT to use:**

• Projects that derive versions from commit messages (conventional commits paradigm)
• Internal-only code that is never published to a registry

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: The Changeset File Format

A changeset is a markdown file in `.changeset/` with YAML frontmatter mapping package names to bump types and a markdown body for the changelog entry.

---
"@myorg/core": minor
"@myorg/cli": patch
---

Add support for custom templates in the core package.
The CLI now passes template options through to core.

**Key points:** File names are randomly generated (e.g., `brave-dogs-dance.md`) to avoid merge conflicts. The YAML maps package names to `major`, `minor`, or `patch`. The markdown body becomes the CHANGELOG.md entry verbatim. Use `changeset --empty` for changes that should not trigger a release (CI config, docs).

See [examples/core.md](examples/core.md) for changeset file examples and the `--empty` pattern.

---

Pattern 2: Configuration (.changeset/config.json)

The config file controls versioning behavior, changelog generation, and publishing access.

{
  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

**Critical options:**

• `access`: `"restricted"` (default) or `"public"` -- **must be `"public"` for public npm packages**
• `baseBranch`: branch changesets compares against