| name | github-release-best-practices |
| description | Background reference for release prep (SemVer, changelog categories). For actual releases, ALWAYS use the release-guard skill and release-manager.sh ship — never manual gh release create. |
| audience | maintainers |
| workflow | github |
GitHub Release Best Practices (reference only)
Canonical procedure: release-guard
Canonical CLI: ./scripts/release-manager.sh ship --execute
GitHub Release creator: .github/workflows/release.yml (tag push only)
Do not invent a second release path. This file is supporting context only.
Prep before ship (via PR to main)
- Bump workspace
version in root Cargo.toml (all members follow workspace).
- Update
CHANGELOG.md with exactly one ## [X.Y.Z] - YYYY-MM-DD (unique version headers — cargo-dist/parse-changelog fails silently on duplicates → empty GitHub Release body).
- Set Released Version in
plans/ROADMAPS/ROADMAP_ACTIVE.md and plans/STATUS/CURRENT.md to vX.Y.Z.
- Merge PR; wait for main CI green.
- Run:
./scripts/release-manager.sh ship --execute
- Confirm notes:
gh release view vX.Y.Z shows ## Release Notes content (v0.1.34/v0.1.35 format).
Semver (0.x)
| Change | Bump |
|---|
| Breaking | minor or major (team call) |
| Feature | minor preferred |
| Fix | patch |
Changelog categories
Added · Changed · Deprecated · Removed · Fixed · Security
Forbidden
gh release create vX.Y.Z ...
References
- ADR-034 Release Engineering
.agents/skills/release-guard/SKILL.md./scripts/release-manager.sh
