# Github Release Best Practices

> 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.

- Skill: `d-o-hub/github-release-best-practices` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add d-o-hub/github-release-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/d-o-hub/github-release-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: d-o-hub (https://skillmd.com/u/d-o-hub)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/d-o-hub/github-release-best-practices

---


# GitHub Release Best Practices (reference only)

> **Canonical procedure:** [release-guard](../release-guard/SKILL.md)  
> **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)

1. Bump workspace `version` in root `Cargo.toml` (all members follow workspace).
2. 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).
3. Set **Released Version** in `plans/ROADMAPS/ROADMAP_ACTIVE.md` and `plans/STATUS/CURRENT.md` to `vX.Y.Z`.
4. Merge PR; wait for main CI green.
5. Run: `./scripts/release-manager.sh ship --execute`
6. 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

```bash
# DO NOT — bypasses cargo-dist and release.yml preflight
gh release create vX.Y.Z ...
```

## References

- ADR-034 Release Engineering
- `.agents/skills/release-guard/SKILL.md`
- `./scripts/release-manager.sh`