gh-releases
Releases (solo dev)
A release is a marked, installable point in the history that says "this is a version, use this one." Cut one when someone — a user, another project, or just future-you pulling a known-good build — needs that marker. Not on a calendar, and not for every merge to main; a release with nothing users-facing in it is noise that trains people to ignore your releases. The judgment is: has enough landed that a person would want to move to it on purpose? If yes, ship it; if no, let it accumulate in Unreleased.
The order of operations
Cutting a release is four steps, and doing them in order keeps the version, the tag, and the notes telling the same story:
- Pick the version — from the nature of what changed since the last release (breaking → major, feature → minor, fixes only → patch), per SemVer. The
semverskill makes this call; don't eyeball it. - Finalise the changelog — move everything under
Unreleasedinto a new section headed with that version and today's date. Thekeep-a-changelogskill owns this format. The changelog is now the single source of truth for what's in the release. - Tag it — an annotated tag on the release commit, named exactly for the version with a leading
v:git tag -a v1.2.0 -m "v1.2.0"thengit push origin v1.2.0. Annotated (not lightweight) so the tag carries a date and author. The tag is the release's anchor — the GitHub Release hangs off it. - Publish the release — create the GitHub Release from that tag, with notes.
Notes come from the changelog, not the commit log
The release notes and the changelog section are the same content — so don't write them twice, and don't let GitHub auto-generate a raw list of commit subjects in their place. A wall of fix: …/chore: … lines is a diff, not release notes; it makes the reader do the work of figuring out what actually changed for them.