05 Release

Release

A release is not just a tag. It is a changelog entry, a date, comparison links and a release body — and they must agree with each other.

Order

python tools/ghagent.py changelog check
python tools/ghagent.py changelog suggest --since v1.1.0
python tools/ghagent.py changelog release 1.2.0 --write
python tools/ghagent.py changelog check
python tools/ghagent.py changelog notes 1.2.0 > release-body.md
gh release create v1.2.0 --notes-file release-body.md --title v1.2.0

What release does

Step	Result
Validates the version	refuses a non-SemVer version or one that already exists
Validates [Unreleased]	refuses when there are no entries
Moves the sections	[Unreleased] is empty again, the new version carries the date
Updates the links	[Unreleased]: …/compare/v1.2.0...HEAD, [1.2.0]: …/compare/v1.1.0...v1.2.0
Re-checks the file	errors are printed immediately, not discovered a week later

Without --write the command only shows what would change.

Choosing the number

Change	Number
a fix	patch 1.2.3 → 1.2.4
a new capability, compatible	minor 1.2.3 → 1.3.0
a breaking change	major 1.2.3 → 2.0.0
before 1.0.0	0.y.z: a minor may break, and that is stated explicitly

How to write an entry

Poor	Good
fix: off-by-one in ExpiryCalculator	"the days-to-payment counter no longer loses a day"
refactor	"synchronisation runs as one request instead of three"
"various improvements"	three separate entries with an observable effect
"breaking change" as its own section	**Breaking:** inside the entry, in its type section

An entry addresses a user: they should understand what changed in their work without reading the code.

Traps

Trap	Symptom	Action
A changelog built from the commit log	entries like Merge pull request #12	rewrite them in human words
A version without a date	## [1.2.0]	release sets the date
Two entries for one version	changelog.duplicate	merge them
A forgotten comparison link	[1.2.0] does not open	release adds it
A tag with no notes	an empty release	changelog notes produces the text

Done means

• changelog check exits 0.
• changelog notes gives text that can be sent as is.
• The tag vX.Y.Z exists, signed by the owner, and the changelog entry matches it.

Next

• Platform traps.
• Import into another agent.