releasing

name	releasing
description	Authoring a changeset, or cutting a release for @vuetify/v0 and the @paper/* design systems. Use when writing a .changeset/*.md file, deciding what belongs in changelog copy, re-entering or exiting changesets pre/beta mode, or reviewing a Version Packages PR. Covers the changeset content contract, the two version domains, and optional pre-channel workflow.

Releasing

Changesets-driven. Pushing to master opens/updates a "Version Packages" PR; merging it publishes to npm (tokenless OIDC) and mints the GitHub releases (.github/workflows/release.yml).

The branch model — which base branch a PR targets by change type — lives in the root CLAUDE.md and is always loaded. This skill covers what happens once the PR is on the right branch.

Commands

pnpm changeset         # Author a changeset — once per change
pnpm release:prepare   # Pre-release validation (validate + build)

Publishing is automated via the Version Packages PR on master — do not npm publish by hand except the first create of a new scoped package (OIDC cannot PUT a name that does not exist yet). That one-shot is npm publish --access public from a logged-in human, then add a trusted publisher (GitHub Actions / org vuetifyjs / repo 0 / workflow release.yml / environment empty). Every package needs publishConfig.access: public before that PUT.

npm view 404 on a brand-new name after a successful + pkg@version is packument lag — the version URL can 200 while the packument is still 404. Do not abort the GitHub-release step on that.

A changeset file must not mix a public package with a private one (privatePackages.version: false treats private as ignored; changesets rejects mixed files). Un-private the DS if this cut is meant to ship it; do not strip it from the changeset as a workaround unless it should stay unpublished.

Version Packages review (before merge)

The bump in that PR is the next published version. It is not held for a milestone.

1. Read the title (1.1.0 vs 1.0.6).
2. Every pending .changeset/*.md on master — any "@vuetify/v0": minor (or major) is that bump.
3. What is still on dev that you wanted in this minor?
4. If (2) and (3) disagree: do not merge. Retarget the stray feat PRs to dev, or accept this minor is the master feats and the dev train is the next minor.

dev → master is a merge commit, never squash. Do not unpublish if another published package depends on v0 with a caret range.

Agents do not merge this PR or cut dev→master unless John says so.

Changeset content contract

The .changeset/*.md body renders verbatim into the changelog and GitHub release notes — it is release-note copy, not a commit message. Don't budget by character count; budget by what belongs:

• First line — conventional-commit summary type(Scope): what changed (#PR), written from the consumer's side, not the diff's. It stands alone as the whole changeset when it already answers both questions a consumer asks — does this affect me, and must I do anything? A title that instead restates the diff (what code moved) is a commit message in changeset frontmatter — that is the failure to avoid, body or not.
• Body (optional) — add one when the title can't answer those questions itself: a behavior delta, a performance change worth quantifying (state the magnitude), a breaking/migration step, or new public options or escape hatches. Length is earned by impact, not padded to a target.
• Never the mechanism — internal composables touched, private fields, refactors mirrored from a sibling go in the PR description and commit body, never the changelog.

Two version domains

• Substrate — @vuetify/v0 is the sole published substrate, versioned and released on its own v<version> GitHub release. @vuetify/paper is private/dormant and no longer part of the changesets fixed group.
• Design systems (@paper/*, e.g. @paper/genesis) version and release independently, each on its own name@version release. Note @paper/genesis depends on @vuetify/v0, so a substrate major bump (e.g. 1.x → 2.0.0) leaves genesis's ^ range and changesets will also bump + republish genesis. That is expected — review it in the "Version Packages" PR before merging.

Pre / beta channel (optional)

Stable releases are the default. The repo is not in changesets pre mode unless .changeset/pre.json exists. To enter a prerelease channel again:

1. pnpm changeset pre enter <tag> (e.g. beta or rc)
2. Ship pre-releases via the normal Version Packages flow (…-<tag>.N under that dist-tag)
3. Before the next stable cut: pnpm changeset pre exit, commit the removal of .changeset/pre.json, then merge the Version Packages PR that produces the clean stable version

Skipping pre exit ships another pre version (or mistags) instead of a real stable.