Release

Release

Typical flow: open PR → merge to main → release checklist → tag + push

Do not tag from a feature branch. Release only from main after shipped work is merged.

Saying release means the full sequence below (Phase 0 → A → B), including commit / tag / push for the release artifacts unless the user says otherwise (e.g. “prepare the release but don’t push”).

User shorthand

Phase 0 — Open PR

Run before merge and version bump. Follow the pr skill.

1. Branch — work must be on a feature branch (not main). Create one if needed; commit release-prep changes (skill edits, version, changelog) on that branch when this pack or app is what you are shipping.
2. Open or reuse PR — if an open PR already exists for the branch, use it; otherwise push (user asked to release ⇒ push is in scope) and gh pr create.
3. Note the PR number and URL before merging.

Skip Phase 0 only when

• An open PR for the work already exists → continue at Phase A, or
• HEAD is already on main, clean, and the commits to ship are already merged → continue at Phase B (tag/version only). Do not invent an empty PR.

Phase A — Merge PR to main

Run before tagging. Prefer merging the PR from Phase 0 (or the existing open PR).

1. Confirm the PR — open PR exists, CI/review acceptable, scope matches what the user asked to ship. Note the PR number.

2. Merge via GitHub CLI when GitHub is the host (preferred):

   gh pr merge <number> --merge --delete-branch
   

   Use --squash or --rebase only when the team explicitly requests it; default is --merge.

3. Sync local main:

   git checkout main
   git pull origin main
   

4. Verify — git log -1 --oneline shows the merge commit on main.

Local branch only (no PR)

If work never went through a PR (rare — quick solo fix) and the user still said release, open a PR first (Phase 0) unless they explicitly waive it. If they waive PR:

1. Ensure the branch is clean (no uncommitted changes).
2. git checkout main && git pull origin main
3. Merge the branch per project convention (prefer --ff-only when possible).
4. Resolve conflicts before continuing. Do not release with unresolved conflicts.

Phase B — Release checklist

All steps run on main after Phase A (or when Phase 0/A were correctly skipped because work was already on main).

If version / changelog were already landed in the merged PR, Phase B is: verify → tag → push tag → gh release create. Do not double-bump.

Pre-release gate

• Scoped from last tag (git log vLAST..HEAD, git diff --stat vLAST..HEAD)
• Version bumped in every place the project syncs
• Changelog entry written (grounded in the diff)
• Build + tests green
• Docs updated if public API or behavior changed
• Tag / push in scope (default yes when the user said release)

Checklist

1. Version policy — infer from repo (semver tags, conventional commits, or project docs such as .github/commands/release.md)
2. Bump — update version in all synced places (e.g. package.json, apps/*/package.json, lockfiles if required, app manifests) if not already in the merged PR
3. Changelog — add entry (create CHANGELOG.md / docs/changelog.md if the project uses one and it is missing). Group by user-visible domain; ban filler bullets.
4. README — when the project ships from main with a version badge or "current release" line, update in the same release commit
5. Docs — run document organize checks if the project has a docs tree
6. Code docs — JSDoc / docstrings on new public APIs if that is project norm
7. Verify — production build and tests (follow project release command if present)
8. Commit — if Phase B still has uncommitted release files: conventional message, e.g. release: vX.Y.Z — <short summary>. Stage only release files — exclude unrelated untracked WIP. Prefer landing these in Phase 0’s PR so main only needs a tag after merge.
9. Tag and push — git tag vX.Y.Z, then git push origin main (if needed) and git push origin vX.Y.Z, then gh release create when GitHub is the host

Hotfix

If patching production: confirm base branch (tag vs main), bump patch only unless breaking.

Conventional commits (if used)

• feat: → minor
• fix: / chore: → patch
• Breaking change → major (confirm with user if unclear)

Report

• PR opened/merged (number + URL) when Phase 0/A ran
• New version number
• Changelog summary
• Commands run and results
• Anything left manual (store submission, deploy, etc.)

Skill pack repo (cursor-agent-skills)

When releasing this distribution (not an app under development), use the same Phase 0 → A → B flow:

1. Branch + bump version and syncedAt in manifest.json (semver)
2. Add section to CHANGELOG.md for the new version
3. Run node scripts/validate-skills.mjs
4. Update README if skills were added or renamed
5. Open PR → merge → sync main
6. git tag -a vX.Y.Z and gh release create vX.Y.Z with notes from the latest changelog section only
7. Remind users to git pull and run install.sh or install.ps1

Related skills

• pr — open PR (Phase 0; user says go for PR-only)
• document — changelog and docs accuracy
• test — verify before tagging