Carry standing text on every release¶

Goal: put the text that is true of every release — what the artefacts are, which one to pick, how to verify them — on the release page, without writing it into the changelog seventeen times.

A release body generated from commits answers "what changed". For a project that publishes artefacts, a consumer landing on the release page usually needs something else first: which licence variant to download, what the profiles contain, how to check a signature. None of that comes from commits, and none of it changes between releases.

Name the files¶

# .colophon.yaml
release_notes:
  standing:
    prefix: docs/release-preamble.md
    suffix: docs/release-verification.md

The prefix opens the release body and the suffix closes it. Both are optional, so if all you want is a verification footer, name only the suffix.

There is no placement setting: the key's name is the placement. That is why there are two keys rather than one — a project usually wants a short orientation above the news and the long reference material below it, and one file could only be in one place.

Write the files¶

They are ordinary Markdown, included exactly as written. No templating, no variables, no substitutions.

<!-- docs/release-preamble.md -->
## Which build do I want?

`*-lgpl-*` for redistribution in a closed-source product; `*-gpl-*` when your
own licence is compatible and you want the extra codecs.

Keep the prefix short. It sits above the changelog on every release, so length there is paid by every reader, every time.

Check it before you release¶

plan reads the manifest and warns about a file it cannot find:

$ colophon plan

Warning: .colophon.yaml names docs/release-preamble.md as standing release text
and it is not in the repository; a release cut now would not carry it

propose warns about the same thing. This is the check worth relying on, because a missing file does not stop the release — colophon warns and publishes without that block. By the time release says so the release exists, and fixing it means editing a published release.

What a release then carries¶

docs/release-preamble.md      ← prefix

## What's Changed             ← the generated notes
- feat: the thing

docs/release-verification.md  ← suffix

The files are read at the released commit, like CHANGELOG.md and the manifest itself, so a release carries the text that was true when it was cut. Correcting a figure changes future releases and leaves published ones alone.

CHANGELOG.md does not get this text. It belongs to the release object, which is what a consumer reads; in the changelog it would repeat once per release, and correcting it would mean editing history.

In a monorepo¶

A component inherits the root's blocks and can replace either one:

release_notes:
  standing:
    prefix: docs/preamble.md
    suffix: docs/verify.md

components:
  cli:
    version: own
    standing:
      prefix: cli/docs/preamble.md   # the root's suffix still applies

What this is not¶

Standing text is the project's, not a release's. No commit can change it — there is no trailer for it, deliberately. Release-Note: is how a commit says something about the release it is part of; this is what is true of all of them. It lives in a file so that changing it goes through review like any other change.

See also: Write a release note for the per-release prose, and the release manifest reference.