Commit trailers¶
colophon reads two annotations out of commit messages. Both are git trailers, and one of them also has a fenced-block form for longer text.
What counts as a trailer¶
Git only treats a line as a trailer when it sits in the message's last
paragraph. A Key: value line followed by more prose is ordinary text, and
colophon will not read it.
feat: add the widget
Some explanation of the change.
Release-Note: The widget config key moved to widget.enabled.
Release-As:¶
Sets the version for this release, overriding the computed one.
| Value | A semantic version. A leading v is accepted and stripped. |
| Scope | Honoured wherever it appears among the commits being considered. |
| Conflict | Two different values in one range is an error, not a tie-break. |
| Invalid value | An error. It does not fall back to the computed version. |
| Reported as | Note: version set to <v> by a Release-As: trailer |
See Set the version explicitly.
Release-Note:¶
Contributes prose to the release's notes section.
| Trailer key | release-note |
| Fence info string | release-note |
| Per commit | Any number, in the order they appear in the message. |
| Ordering | Fenced blocks always precede trailers, as a consequence of the last-paragraph rule. |
| Unterminated block | Ignored, rather than read to the end of the message. |
Trailer form, for one line:
Fenced form, for anything longer:
```release-note
Gadgets built before 0.2 need regenerating.
Run `gadget regen` once after upgrading.
```
Where the section appears and what it is headed is set in
.colophon.yaml. See
Write a release note.
Conventional Commits¶
The subject line's type is not a trailer, but it is the other thing colophon reads out of a commit. See How the version is decided for the type-to-bump mapping and the breaking-change rules.