cutting-a-release

Files (2)

• RUNBOOK.md
• SKILL.md

SKILL.md (first lines)

# Cutting a Superpipelines Release

Cut a version release after the feature PR(s) are merged into `main`. Full step detail + gotchas live in [RUNBOOK.md](RUNBOOK.md) — read it before acting.

## Hard constraints (read first)

- **`main` is branch-protected.** No direct `git push origin main`. Every change goes through a PR. `gh pr merge <n> --squash --admin` bypasses `REVIEW_REQUIRED` (CI must still be green) — **confirm with the user before any `--admin` override.**
- **JSON must be BOM-free.** Never `Set-Content -Encoding UTF8` for JSON. Use the Edit tool or `python3` writes (`encoding="utf-8"`).
- **5 version targets must agree** before tagging: `package.json`, `.Codex-plugin/plugin.json`, `.Codex-plugin/marketplace.json` (`plugins.0.version` — NOT the top-level `1.0.0`), `.cursor-plugin/plugin.json`, `AGENTS.md` (`- **Project Version**: vX.Y.Z`). First 3 listed in `.version-bump.json`; last 2 are manual.
- **Tag ↔ changelog convention:** every tag `vX.Y.Z` MUST have a matching `## X.Y.Z` CHANGELOG entry and a `## vX.Y.Z` RELEASE-NOTES entry before `gh release create`.
- **gh CLI in Bash tool:** never `--body @'...'@` (PowerShell here-string, fails). Write the body to a temp `.md`, use `--body-file`, then `rm` it. Keep temp files out of commits.

## Workflow

1. **Preflight** — `git fetch origin`; confirm `origin/main` has the feature merge; verify all 5 version targets agree and equal the intended vX.Y.Z (`npm run check:versions` covers 6 including `.codex-plugin`); check tag/release naming convention (`vX.Y.Z — <Title Case Name>`). **Profile-drift check:** confirm the latest "Profile drift review" issue (opened monthly by `.github/workflows/profile-drift.yml`) is closed or its findings are consciously deferred in the release notes; a `model_tiers_version` older than 90 days blocks unless deferred.
2. **Sync local main** — `ExitWorktree action:keep` if in a worktree; `git checkout main && git pull --ff-only origin main` (clear stale untracked blockers first — diff against `origin/main`).
3. **Draft doc entries** — add `## X.Y.Z` to `CHANGELOG.md` and a `<release_entry>` to `RELEASE-NOTES.md`, mirroring the previous entry's format exactly. Source bullets from real changes; do not invent.
4. **Land docs via PR** — branch `release-notes-X.Y.Z`, commit, push, `gh pr create` (`--body-file`), wait for CI pass, confirm intent, `gh pr merge --squash --admin --delete-branch`, re-sync main.
5. **Create release + tag** — extract the new CHANGELOG section as the release body, append the install line, `gh release create vX.Y.Z --target main --title "vX.Y.Z — <Title>" --notes-file <tmp>`.
6. **Verify** — tag commit == `origin/main`; release not draft/prerelease; `Closes #N` issues CLOSED; follow-up issues still OPEN.
7. **Aiboarding pointer** (optional) — if release docs don't touch the 3 AIBOARDING sections, no-op advance `last_synced_commit` to HEAD via the same PR + `--admin` flow. Expect one residual drift nag on the bump commit — STOP, do not chase.

## Gotchas checklist

- [ ] Bumped `plugins.0.version` in marketplace.json, not top-level `1.0.0`.
- [ ] All 5 version targets agree before tagging (`npm run check:versions`).
- [ ] Latest profile-drift review issue closed or explicitly deferred.
- [ ] CHANGELOG + RELEASE-NOTES entries exist before `gh release create`.
- [ ] Used `--body-file` for all gh bodies (never `@'...'@`).
- [ ] No direct push to main — everything via PR.
- [ ] Got user OK before any `--admin` override.
- [ ] Temp files cleaned up, kept out of commits.

From gustavo-meilus/superpipelines, MIT.

More from gustavo-meilus/superpipelines