Cutting an aiboarding Release
Cut a version release after the feature work is merged into main. Full step detail + gotchas live in RUNBOOK.md - read it before acting.
Hard constraints (read first)
mainis NOT branch-protected. Directgit push origin mainworks; no PR or--admindance required. (Confirm with the user if they prefer a PR anyway.)- No CI. No GitHub Actions gate - verification is
rg/Read assertions +python3 -c "import json; json.load(...)". Nothing waits on green checks. - One version target. Only
.claude-plugin/plugin.json(version) carries the version.marketplace.jsonhas NO per-plugin version field - do not add one. There is no package.json /.version-bump.json/.cursor-plugin/ CLAUDE.md version. - JSON must be BOM-free. Never
Set-Content -Encoding UTF8for JSON. Use the Edit tool orpython3writes (encoding="utf-8"). - Tag ↔ changelog convention (stated in
CHANGELOG.mdheader): every tagvX.Y.ZMUST have a matching## X.Y.ZCHANGELOG entry and a## vX.Y.ZRELEASE-NOTES entry beforegh release create. - gh CLI in Bash tool: never
--body @'...'@(PowerShell here-string, fails). Write the body to a temp.md, use--body-file, thenrmit. Keep temp files out of commits. - Title form:
vX.Y.Z - <Title Case Feature Name>(matches existing releases).
Workflow
- Preflight -
git fetch origin; confirmorigin/mainhas the feature merge; verifyplugin.jsonversionequals the intended vX.Y.Z; check tag/release naming convention. - Sync local main -
git checkout main && git pull --ff-only origin main. - Bump version if needed - if the feature work did not already bump
plugin.json, do it now (Edit tool, BOM-free). - Draft doc entries - add
## X.Y.ZtoCHANGELOG.md(with trailing---separator) and a<release_entry>toRELEASE-NOTES.md, mirroring the previous entry's format exactly; extend the<overview>milestone sentence and the Roadmap. Source bullets from real changes; do not invent. - Commit to main -
git addthe changed files, commit,git push origin main. (No PR needed - main is open.) - 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>. - Verify - tag commit ==
origin/main; release not draft/prerelease; it shows asLatest.
Gotchas checklist
- Bumped
plugin.jsonversiononly - did NOT add a version field to marketplace.json. -
plugin.jsonversion == intended vX.Y.Z before tagging. - CHANGELOG (
## X.Y.Z+---) and RELEASE-NOTES (<release_entry>+ overview + roadmap) entries exist beforegh release create. - Used
--body-filefor all gh bodies (never@'...'@). - JSON edits BOM-free.
- Temp files cleaned up, kept out of commits.