Explanation¶

Understanding-oriented material: how colophon works, and why it works that way.

Concepts¶

• How the version is decided — the type-to-bump mapping, why the decision is a pure function, and why a breaking change below 1.0.0 is held to a minor.
• Tagging what actually landed — the idea colophon exists for: why the merge request cannot be trusted to say which commit merged, and why publish runs before propose.
• Why release notes come from commits — why the merge request description is the wrong source when a project merges fast-forward.

Components¶

• Components — how the code is arranged, and the two extractions that shaped it.

The short version¶

colophon does three things, and only the third is unusual.

It works out what version the commits have earned, which is ordinary conventional-commit arithmetic with one deliberate deviation below 1.0.0. It opens that release as a merge request, re-cut from the target every run so it can never be stale. And when that request merges, it resolves the commit that actually landed from the target branch itself, rather than asking the forge which commit it thinks merged.

The third one is the whole point. A forge can report a request merged before its commit is reachable, an automatic rebase leaves the recorded head pointing at a commit that no longer exists, and under a fast-forward merge the request's body is not in git at all. Anything that trusts those sources tags the wrong commit some of the time, and it does so quietly.