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.