Skip to content

Set the version explicitly

Goal: release a specific version, rather than the one the commits worked out.

The usual reason is promoting to 1.0.0. Below 1.0.0 colophon holds a breaking change to a minor bump, precisely so that declaring a stable API stays a decision somebody makes rather than one that falls out of a commit message.

Add a Release-As: trailer

The trailer goes in the commit message, in its own paragraph at the end.

git commit --allow-empty -m "chore: promote" -m "Release-As: 1.0.0"

0.1.0 → 1.0.0 (major)

Decided by 1 commit:
  4118ff44 minor  feat: change the shape of the thing

1 commit moved nothing.

Note: version set to 1.0.0 by a Release-As: trailer

colophon says which mechanism produced the answer. It does not quietly substitute the version and leave you to work out why the arithmetic looks wrong.

It can go on any commit in the range

The trailer is honoured wherever it appears among the commits being considered, so it does not have to be the last one. An empty commit is simply the tidiest way to add one after the fact.

Rules worth knowing

  • A v prefix is accepted. Release-As: v1.0.0 and Release-As: 1.0.0 both work, because every tag in this estate is written with the prefix and rejecting it would only be pedantry.
  • The value must be a valid semantic version. Anything else is an error, not a fallback to the computed answer.
  • Two different Release-As: values in one range is an error. colophon refuses rather than picking one, because either choice would be wrong half the time.
  • It must be a real trailer. Git only treats a line as a trailer when it sits in the message's last paragraph. A Release-As: line followed by more prose is not a trailer and will not be read.

Reference

Trailer syntax and the full set of keys colophon reads is in the trailers reference.