Hold a release back¶
Goal: stop a computed release being tagged, without hiding it and without reverting anything.
The version can be right and the moment still wrong: a downstream migration is mid-flight, a dependent service has not deployed, an announcement is not ready.
Commit a hold¶
Add .colophon.yaml to the release branch:
plan reports it, and so does the Release merge request:
0.1.0 → 1.0.0 (major)
HELD — waiting on the downstream migration
The release is computed and shown, but publish will not act on it.
Decided by 1 commit:
4118ff44 minor feat: change the shape of the thing
The release is still computed and still shown. A hold stops publish acting on
it; it does not hide the pending release. That is deliberate: a held release
nobody can look at is one nobody can safely decide about.
Always give a reason¶
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.
Lift it¶
Remove the file, or set hold: false, and merge that to the release branch. The
next publish proceeds normally.
What this file is not for¶
.colophon.yaml holds two things and no more: the hold, and the shape of the
release-notes section. It carries no version overrides.
An earlier design did carry them, an exact version and a bump floor among them,
and they were moved to a Release-As: commit trailer because the mechanism
should match the lifetime. A hold is a state the project is in and stays in
until lifted, so a committed file is right for it. A version override applies to
one release and should expire with it, which a file does not do.
To set a version, see Set the version explicitly.
Reference¶
The full schema is in the release manifest reference. An unknown field is an error rather than a warning, so a typo fails loudly instead of holding nothing.