releases-and-changesets

name

releases-and-changesets

description

Author changesets and prepare releases under the fixed (lockstep) versioning policy. Use whenever creating a `.changeset/*.md`, scoping a release, choosing a bump level, running `bun run version` / `bun run release` / `bun run release:with-version`, or adding a new publishable package. Trigger on cues like "changeset", "release", "publish", "version bump", "patch", "minor", "major", "fixed versioning", "lockstep".

Releases and Changesets (Fixed / Lockstep Versioning)

Canonical rule: .cursor/rules/release-version-alignment.mdc. Lockstep package list (source of truth): .changeset/config.json (the fixed block). Enforcement scripts:

• scripts/check-changeset-patch-only.mjs (bun run check:changeset-patch-only) — rejects any pending .changeset/*.md declaring minor / major. Wired into verify:publish and as the first step of release:with-version.
• scripts/check-fixed-versioning.mjs (bun run check:fixed-versioning, also wired into verify:publish) — fails if publishable package versions diverge or skip a patch step from the published baseline. Consumer-facing docs: docs/setup/publishing.md and the "Versioning Policy" section in README.md.

Policy in one paragraph

All publishable @pie-players/* packages are released with a fixed (lockstep) version. At any published version, every package in the suite carries that same version number — there is no per-package version drift. Every release bumps every publishable package, including ones whose source did not change. That is expected, not a bug to fix. While we are pre-1.0 (the current 0.x.y line), every release is a patch bump, even for breaking changes — see "Bump level" below.

Bump level — patch only

Until the maintainer rewrites the rule, every release is patch. Pre-1.0 semver allows breaking changes within a 0.x line, and the lockstep invariant already keeps consumers aligned.

• Author every changeset entry as patch. Do not propose minor / major unless the maintainer explicitly lifts this constraint and updates .cursor/rules/release-version-alignment.mdc.
• A pending changeset declaring minor / major is a release blocker — flip it to patch before running bun run release:with-version. The auto-generated temporary all-packages changeset is always patch; the highest-declared bump in .changeset/ wins for the lockstep set, so a stray major upgrades the whole suite.
• Document breaking changes in the changeset body (so consumers see them in the assembled CHANGELOG.md), but ship them under a patch bump.

Authoring a changeset

When making changes that should ship in a release:

bun run changeset

Use patch for every entry. The changeset must scope to the publishable packages whose source actually changed (the lockstep coverage for the rest is added automatically by release:with-version). When in doubt about which packages to list, default to all publishable packages — the result is the same either way under lockstep.

When to add a changeset

• Any change that ships in dist (source edits in publishable packages, CE registration changes, contract updates).
• New publishable package — see the "Adding a publishable package" section below.
• Skip for: docs-only changes that do not ship to npm, CI/lefthook tweaks, changes confined to apps/* or tools/* (those are not publishable), pure dev-script edits.

Release commands

Command	What it does
bun run changeset	Interactive: author a .changeset/<name>.md.
bun run version	Apply pending changesets to package versions.
bun run verify:publish	Full pre-publish gate (build + every check:*).
bun run release:with-version	Canonical local-publish command. Auto-generates a temporary all-packages patch changeset (lockstep coverage), runs version, restores workspace ranges, runs check:npm-auth + verify:publish + the workspace test suite, publishes via release, restores ranges again. Mirrors the CI release path.
bun run release	Publish wrapper invoked by release:with-version and CI: builds the publishable packages, runs changeset publish with workspace ranges resolved, then publishes the preloaded-player bundles. Don't run directly — use release:with-version.
bun run release:label / release:label:push	Tag a coordinated release wave (annotated tag, default pie-players-YYYY.MM.DD).

Local publishing

bun run release:with-version is the canonical command. To run it locally you need:

• The current checkout is authoritative. When the user asks to publish locally, confirm the current branch and working tree state, then publish from that exact codebase and branch. Do not route the request through the GitHub workflow, master, main, or develop unless the user explicitly asks to switch branches or use the workflow.
• NPM auth in .env. The release step is wrapped in dotenvx run -f .env, and check:npm-auth (the first preflight step) also loads .env via dotenvx. The repo's .env contains the NPM_TOKEN for @pie-players publish access; no separate npm login is needed.
• A clean working tree on the branch you're releasing from (typically the branch currently checked out). The script writes to package.json and CHANGELOG.md files during version.
• Outside the sandbox. The command runs bun run test, which triggers Playwright and other browser-bound suites; invoke with required_permissions: ["all"].

Bump-level note: the auto-generated temporary changeset only adds patch-level entries for every publishable package, but if a regular .changeset/*.md already declares a higher bump (minor / major) for some package, the highest declared bump wins for the whole lockstep set. When you want a patch-only release, ensure no pending changeset declares minor / major.

Adding a publishable package

When adding a new package under packages/* that ships to npm:

• Add it to the fixed block in .changeset/config.json in the same change set that introduces the package. A publishable package outside the fixed block silently breaks the lockstep invariant.
• Run bun run check:fixed-versioning (also part of verify:publish) to confirm.

Do not

• Author a minor or major changeset. Patch-only is the policy until the maintainer rewrites .cursor/rules/release-version-alignment.mdc. Even breaking changes ship as patch on the 0.x.y line.
• Prepare release bumps for only a subset of changed packages. "Only package X changed, so only bump X" is the wrong framing for this repo — every publishable package gets the new version regardless of whether its source changed.
• Remove packages from the fixed block to "unblock" a release. That hides drift. Escalate to the maintainer instead.
• Run npm publish directly, or invoke bun run release directly. Use bun run release:with-version so the temporary all-packages changeset, workspace-range rewrite, NPM token load from .env, and preflight checks all run in the right order.

Pre-publish smoke (recommended before pushing a release branch)

bun run verify:publish

This runs build + check:fixed-versioning, check:package-metadata, check:custom-elements, check:ce-define-safety, check:publint, check:types-publish, check:pack-exports, check:pack-smoke, check:deps, check:source-exports, check:consumer-boundaries, check:ce-consumer-contract, check:runtime-compat, check:node-consumer-imports, check:bundle-safety, check:math-rendering-version, check:engine-core-purity.

Related rule

• .cursor/rules/playwright-sandbox.mdc — bun run release:with-version runs bun run test, which can trigger Playwright; invoke with required_permissions: ["all"].