release-runbook

# Release Runbook ## Overview Create a new release for this repo by updating semantic versions, maintaining `CHANGELOG`, tagging the release, and publishing it to GitHub via `gh`. ## Workflow (PowerShell) ### 1) Pre-flight checks - Confirm repo and auth: - `gh repo view --json nameWithOwner,url` - `gh auth status` - Ensure working tree is clean or changes are intentional. ### 2) Decide the version (semantic versioning) - Use `MAJOR.MINOR.PATCH`. - **MAJOR**: breaking changes - **MINOR**: new features, backward compatible - **PATCH**: fixes only - If unsure, summarize changes and pick the smallest correct bump. ### 3) Update version and changelog - Update `PROJECT_VER` in `CMakeLists.txt`. - Update `CHANGELOG` (add a new section for `vX.Y.Z` with date and highlights). - Keep entries concise and user-facing; group by Added/Changed/Fixed/Breaking. ### 4) Commit the release prep - Commit `CMakeLists.txt` and `CHANGELOG` together. - Use Conventional Commits, e.g.: - `chore: bump version to X.Y.Z` ### 5) Tag the release - Create an annotated tag: - `git tag -a vX.Y.Z -m "Release vX.Y.Z"` - Push the tag: - `git push origin vX.Y.Z` ### 6) Create the GitHub release - Use the changelog section as release notes: - `gh release create vX.Y.Z --title "Release X.Y.Z" --notes "Release notes here"` - If the repo uses a template, follow it exactly. ## Quality checklist - `PROJECT_VER` matches the tag `vX.Y.Z`. - `CHANGELOG` contains the new version section and date. - Tag is pushed and visible on GitHub. - Release notes match the changelog highlights. ## Troubleshooting - If tag exists, increment the version and retry. - If release creation fails, re-run `gh release create` with the same tag.