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)
mainrequires a pull request and its required checks. Do not push release changes directly.- Exact-SHA CI evidence is required. Before tagging, run
bash tools/verify-release-sha <target-sha>; local checks do not replace it. - One version target. Only
.Codex-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/ AGENTS.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; set the explicit target withtarget_sha=$(git rev-parse origin/main)and runbash tools/verify-release-sha "$target_sha". - 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 through a pull request -
git addthe changed files, commit, open a pull request, and merge only after required checks pass. Refreshtarget_shafromorigin/mainand runbash tools/verify-release-sha "$target_sha"before tagging. - 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.