Why release notes come from commits¶

A generated release is a list of subject lines, and a subject line is a summary. The thing a reader most needs, this config format changed, edit the file before you upgrade, is usually written in the commit body by the person who knew it. Nothing looks there.

So colophon reads it, out of a Release-Note: trailer or a fenced block.

The alternative, and why it does not work here¶

releaser-pleaser reads this from a merge request description. colophon cannot, and the reason is mechanical rather than a matter of taste.

Every project in this estate merges fast-forward with squash off by default, and under those settings a merge request's description is not in the git history at all. Reading one means asking the forge to map each commit back to its merge request, which is:

• an API call per commit;
• unavailable on Bitbucket without a human-installed app;
• broken for cherry-picked commits, which have no merge request of their own;
• and impossible in a repository read without credentials, which is exactly what plan is designed to be.

That last one is the decisive constraint. plan needs no token precisely so it can be run against any checkout, by anyone, to compare colophon against whatever a project releases with today. A notes source that required credentials would take that away.

It would also depend on how somebody merged¶

Reading the merge request makes the notes depend on whether whoever pressed the button happened to squash. Squashing is a judgement about whether a branch's commits carry historical value. It is not a precondition for having release notes, and tying one to the other means the same change produces different documentation depending on a decision made for unrelated reasons.

The commit message is in the repository whatever anyone did with the merge request. That is the whole argument.

Ordering¶

A commit may carry several notes, and they appear in the order they occur in the message. Fenced blocks always precede trailers, which is a property of git rather than a choice colophon made: a trailer only counts when it sits in the message's last paragraph, so a fenced block appearing after one would stop it being a trailer at all. There is therefore no message in which a trailer precedes a block.

An unterminated fence is ignored rather than read to the end of the message, because the alternative silently swallows the rest of a commit body into a release note.

Placement¶

The notes section prepends by default. These are most often upgrade or migration notes, and a warning printed after the feature list is a warning read too late. A project that disagrees can set placement: append and its own heading in .colophon.yaml.

Standing text, and why the release body stopped being the changelog¶

Everything above is about this release: prose a commit contributed, placed in a section. A project publishing artefacts usually has a second kind of text as well — what the artefacts are, which variant to pick, how to verify a signature. That is constant, correct on every release, and belongs to neither a commit nor a version.

release_notes.standing names a file to open the release body and a file to close it. Two keys named by position, so a project can have both: the short orientation a reader needs before the news, and the long reference material they come back for afterwards. There is no placement value, because with two keys there is nothing left to place.

This has a consequence worth being explicit about, because it changes something that used to be reliably true.

The release body and the changelog's top section were the same text. For a release colophon described, the body it published was the section it wrote — one text with two homes. A project naming standing text breaks that: the release object carries the blocks and CHANGELOG.md does not.

That is deliberate, and the reason is what the changelog is. It accumulates. Text repeated once per release is repeated forever, and correcting a measured figure in it means either editing history or leaving every older section wrong. The release object has no such problem: it is a page describing one release, read by someone who wants to know what to download, and standing text is exactly what they are missing there.

So the rule is now: the changelog records what changed; the release page describes the release. For a project with no standing text those are still the same text, byte for byte, and nothing about it has changed.

A file the manifest names and the commit does not carry does not stop the release. Colophon warns and publishes without that block, because a repository that cannot release over a deleted documentation file is worse than a release missing a paragraph. The warning matters more than it looks, though, so plan and propose print it too — before a release exists, which is the only point at which the fix is free.