Release manifest (.colophon.yaml)¶
An optional file committed to the release branch. It holds a release back, and shapes the release-notes section. It carries nothing else.
Absent, empty, or comments-only, it means the same as every field at its default.
Schema¶
| Field | Type | Default | Meaning |
|---|---|---|---|
hold |
boolean | false |
Compute and display the release, but do not let publish act on it. |
reason |
string | empty | Shown wherever the hold surfaces. |
release_notes.placement |
string | prepend |
prepend or append. Where the notes section sits. |
release_notes.heading |
string | empty | Section heading. Empty means Notes. |
An unknown field is an error, not a warning. A typo therefore fails loudly rather than silently holding nothing.
Example¶
hold: true
reason: waiting on the downstream migration
release_notes:
placement: prepend
heading: Upgrading
Notes on the fields¶
reason is optional to the parser and not optional in practice. A hold with
no stated reason is one nobody else can lift, because they cannot tell whether
the thing it was waiting for has happened.
placement defaults to prepend because these are most often upgrade or
migration notes, and a warning after the feature list is a warning read too
late.
What is deliberately absent¶
There are no version overrides here. An earlier design carried them, an exact
version and a bump floor among them, and they moved to a
Release-As: trailer because the mechanism should
match the lifetime of the thing it controls. A hold is a state a project is in
and stays in until lifted, which suits a committed file. A version override
applies to exactly one release and should expire with it, which a file does not
do.