changeset-release-pr

name	changeset-release-pr
description	Prepare the next Roomote release PR: review what merged to develop, fill missing release notes, confirm patch/minor/major when unspecified, run the product version script, and open the final version-and-changelog PR. Use when asked to prep, cut, or write notes for a release.

Changeset Release PR

Use this skill to prepare the single release PR that cuts the next Roomote version. The deliverable is a normal PR against develop containing the root version bump, final CHANGELOG.md entry, and deletion of every consumed pending changeset. Merging it makes CI open the frozen Promote PR to main.

How releases work here

• Roomote has a single product version: the root package.json version field. Workspace package versions are frozen and meaningless because every workspace package is private.
• Changesets are an authoring format only. Feature PRs may add them ahead of time; this skill creates any missing notes locally before versioning.
• pnpm run version (scripts/release/apply-version.mjs) folds all pending .changeset/*.md files into the root CHANGELOG.md, bumps the root version by the highest pending level, and deletes the consumed files. changeset version itself is never run.
• .github/workflows/release.yml does not create another Version PR. After the release PR merges to develop, it freezes release/vX.Y.Z at that merge and opens the Promote PR to main. Merging the Promote PR tags and publishes the release.

Full details: .changeset/README.md and CONTRIBUTING.md#product-releases.

Workflow

1. Establish the last release reference point

Cross-check three signals; they should normally agree:

git tag --sort=-creatordate | head -5
node -p "require('./package.json').version"
head -10 CHANGELOG.md

Use the v<version> tag as the diff base when it exists. If the root version is ahead of the newest tag because a release PR merged but its Promote PR has not shipped yet, use the version-bump commit on develop as the next diff base:

node scripts/release/find-version-commit.mjs <version> origin/develop

Call out the unshipped release and do not merge a later Promote PR before it.

2. Collect what changed since then

develop is squash-only, so --first-parent yields one line per merged PR:

git fetch origin develop
git log v<last>..origin/develop --oneline --first-parent

For anything ambiguous, read the PR body with gh pr view <number> to identify the user-facing or operator-facing impact.

3. Subtract existing pending changesets

find .changeset -maxdepth 1 -type f -name '*.md' ! -iname 'README.md' -print

Read every pending file. A change already covered by a pending changeset must not receive a duplicate note.

4. Classify the remaining changes

• Include user-visible or operator-visible capabilities, behavior changes, fixes to visible symptoms, and notable performance or UX improvements.
• Skip chores, docs-only changes, CI or infrastructure tweaks, internal refactors, and dependency bumps with no visible effect. They ship without a changelog bullet.

5. Confirm the bump level

If the user specified patch, minor, or major, use it. Otherwise ask and include a recommendation based on the actual changes:

• patch — bug fixes and small non-breaking changes only
• minor — backward-compatible new capabilities
• major — breaking behavior changes

Explain that the highest level across all pending changesets determines the single product version. If an existing pending changeset is higher than the user's choice, say that the higher bump will win. Individual notes may carry different levels and are grouped by level in the changelog.

6. Author missing changesets locally

Create one .changeset/<descriptive-slug>.md file per logical release note:

---
'@roomote/web': patch
---

One concise, user-facing summary of the change.

• Always use exactly one package line: '@roomote/web': <level>. Package names are ignored by the release script; the frontmatter carries only bump level.
• Each summary becomes one changelog bullet. Write one tight paragraph with no headings or nested lists.
• Lead with what changed or now works, name the affected product surface, and mention the previous symptom when describing a fix.
• Group closely related PRs when they form one user-facing story. Otherwise keep their notes separate.
• These newly authored files are temporary release inputs. pnpm run version consumes them before the release branch is committed.

7. Generate and verify the release

Start from the current origin/develop tip. If develop advances before the release PR merges, rebuild the release artifacts from the new tip and repeat the audit; do not merely merge the new commits into an already-generated release branch, because their changesets and notes would not have been consumed.

Run the repository-owned version command; never hand-edit the output:

pnpm run version

Then verify:

• package.json contains the expected next version using ordinary semver (patch increments patch, minor increments minor and zeros patch, major increments major and zeros minor and patch)
• the new top CHANGELOG.md section contains every intended note under the correct bump-level heading
• every pending changeset was consumed and .changeset/README.md remains
• workspace package versions did not change
• the diff contains only release artifacts: root package.json, CHANGELOG.md, and deletions of changesets that already existed on the base branch. Locally created missing changesets normally leave no final diff because they are created and consumed in the same working tree.

Run the release-script tests and the repository's appropriate static checks before opening the PR.

8. Open the release PR

Commit the generated release artifacts on a feature branch and open a PR against develop titled Release Roomote X.Y.Z. The PR body should include:

• the previous and next product versions
• the final changelog bullets grouped by bump level
• validation performed
• a note that squash-merging the PR cuts the release and automatically opens the frozen Promote vX.Y.Z to production PR against main

Guardrails

• Never edit CHANGELOG.md or the root version by hand; generate both with pnpm run version, review the result, and commit that output in the release PR.
• Never run or commit changeset version output.
• Never push to release/v*; CI owns frozen release branches.
• Never merge an out-of-date release PR. Regenerate it from the latest develop so every commit included in the cut was part of the release audit.
• Never bump versions in workspace package.json files.
• Do not create the Promote PR manually.
• Ask for the bump level when unspecified; recommend one but let the user decide.
• Do not duplicate existing pending notes or pad the changelog with internal noise.
• Do not multi-package-attribute changesets; always emit one '@roomote/web': <level> line.
• Use the actual version produced by scripts/release/lib.mjs; do not guess semver in the PR title or body.