Release management strategy: canonical CHANGELOG + concise GitHub releases

[benrozsa]

Release Management Strategy — Proposal

Goals

• Consistent, lightweight releases during 0.x
• Single source of truth for details (avoid duplication)
• Fit a PR + auto‑merge workflow

Current State

• Releases exist but notes vary by format
• No canonical CHANGELOG in main (consider adding)

Proposal

• Canonical notes: maintain full details in CHANGELOG.md (Keep a Changelog style)
• GitHub Releases: short “Highlights” + link to matching CHANGELOG section
• Versioning (0.x SemVer‑lite):
  • Patch: docs/CI/metadata
  • Minor: new features or notable config changes
  • Major: breaking changes (rare in 0.x)

Template

• Title: vX.Y.Z — short summary
• Highlights: 3–5 bullets
• Changes: grouped (Docs, CI, Scripts, Config)
• Breaking Changes: when applicable
• How To Update: only if action required
• Compare: previous…current tag link

Process

1. Update CHANGELOG.md for the new version using the template
2. Commit with “release: vX.Y.Z” (or docs(changelog): …)
3. Tag and push vX.Y.Z
4. Create GitHub Release with Highlights + link to CHANGELOG section

Optional Tooling

• Release Drafter if PR labels are used (docs, ci, scripts, config, breaking)
• Otherwise keep it manual (CHANGELOG + short Releases)

Open Questions

• Add CHANGELOG.md now, or after PRs ci(shellcheck): install and run native shellcheck on ubuntu-latest #6 and docs: add AGENTS.md house rules; add PR template and issue forms #7 merge?
• Version cadence preference (batch small docs/ci changes)?

Related

• PR ci(shellcheck): install and run native shellcheck on ubuntu-latest #6: ci(shellcheck): install and run native shellcheck on ubuntu-latest #6
• PR docs: add AGENTS.md house rules; add PR template and issue forms #7: docs: add AGENTS.md house rules; add PR template and issue forms #7
• CI checks issue: Required checks stuck as 'Expected' on PRs #6 and #7 despite passing jobs #8