# Release Runbook

> Prepare and publish a GitHub release with semantic versioning, updating PROJECT_VER and CHANGELOG, tagging, and using GH CLI to publish. Use after major changes or when asked to cut a release.

- Skill: `nibzard/release-runbook` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add nibzard/release-runbook`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nibzard/release-runbook/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, Productivity
- Author: nibzard (https://skillmd.com/u/nibzard)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nibzard/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.