Context
Release notes are currently hand-written for every release (see docs/release_notes/vX.Y.Z.md). This works but is repetitive, and some content is genuinely mechanical (commit list, PR list, contributor list) while other content is genuinely editorial (Highlights, Important Note callouts, migration examples).
The v0.2.0 release exposed this trade-off — the notes came out well, but a lot of the work was retyping information already visible in the PR/commit history.
Options considered
- Do nothing — current approach. Fine for a solo alpha with ~monthly releases.
.github/release.yml — GitHub-native config for grouping auto-generated release notes by PR label. Zero cost, requires PR labelling discipline.- Conventional Commits +
git-cliff / release-please — commit-message-driven CHANGELOG generation. Requires disciplined commit messages at write time.
- Full
semantic-release — end-to-end automation including version bump. Would replace parts of release.yml. Likely over-engineered for an alpha where version bumping is a deliberate manual decision.
A hybrid:
- Add
.github/release.yml with categories mapped to PR labels (e.g. enhancement, bug, docs, tests, ci, chore)
- Adopt PR labelling as a merge-time habit
- Keep hand-writing
docs/release_notes/vX.Y.Z.md for the narrative (Highlights, Important Notes, migration examples)
- Use auto-generated GitHub Release body as a cross-check, not a replacement
What to explicitly NOT automate
- Highlights section — editorial judgement about what matters most
- Important Note callouts — these prevent user surprises and need care
- Migration examples — code snippets tailored to real breaking changes
- Version-bump decision — solo maintainer should keep manual control in alpha
Decision needed
- Do we adopt option 2 for v0.2.1?
- Do we adopt a Conventional Commits standard for the project?
- Or stay fully manual for now?
Related
release.yml already uses generate_release_notes: true on softprops/action-gh-release@v2 — auto notes are currently unformatted- Existing commit history is partially conventional (
chore:, fix:, docs:) — formalising would be a small step
Context
Release notes are currently hand-written for every release (see
docs/release_notes/vX.Y.Z.md). This works but is repetitive, and some content is genuinely mechanical (commit list, PR list, contributor list) while other content is genuinely editorial (Highlights, Important Note callouts, migration examples).The v0.2.0 release exposed this trade-off — the notes came out well, but a lot of the work was retyping information already visible in the PR/commit history.
Options considered
.github/release.yml— GitHub-native config for grouping auto-generated release notes by PR label. Zero cost, requires PR labelling discipline.git-cliff/release-please— commit-message-driven CHANGELOG generation. Requires disciplined commit messages at write time.semantic-release— end-to-end automation including version bump. Would replace parts ofrelease.yml. Likely over-engineered for an alpha where version bumping is a deliberate manual decision.A hybrid:
.github/release.ymlwith categories mapped to PR labels (e.g.enhancement,bug,docs,tests,ci,chore)docs/release_notes/vX.Y.Z.mdfor the narrative (Highlights, Important Notes, migration examples)What to explicitly NOT automate
Decision needed
Related
release.ymlalready usesgenerate_release_notes: trueonsoftprops/action-gh-release@v2— auto notes are currently unformattedchore:,fix:,docs:) — formalising would be a small step