colophon announce¶
Description¶
Tell people a release happened
Read the release a tag carries and hand it to each adapter .colophon.yaml
configures. Discord today; a blog and a newsletter are the reason the adapters
are a seam rather than a webhook call.
It runs after the release object exists — on the tag pipeline, once
colophon release has created it — and reads the release rather than the
changelog, so the words it quotes and the words a reader finds on arrival are
the same.
Usage¶
Run colophon announce --help for the authoritative, always-current flag set.
What an announcement is made from¶
The release notes are the foundation and not the text. Every adapter is built from them and none of them delivers them as they are: a Discord embed wants a title, a colour, a footer and about twelve hundred characters; a newsletter wants a subject line and probably the whole thing; a blog post wants front matter and a permalink.
So an adapter is handed the notes and the facts they were rendered from — project, tag, version, release size, URL — and decides what to make of them.
It announces at least once¶
This is the only thing colophon does that is not idempotent, and it says so.
Everything else has an answer for being run twice. A release that exists is
reported rather than created again. A tag that exists is left alone. A comment
apply posts carries an idempotency key the forge honours, so the provider
returns the existing one.
No provider offers that here. A webhook execution has no such key, so a retried job announces again. Colophon will not manufacture a guarantee out of state it would have to keep correct forever.
An adapter that can tell reports unchanged — a blog post that already
exists, a message a service recognises by key. The Discord adapter cannot, and
never claims to.
What it reports¶
And when something did not go out:
failed discord — 502 Bad Gateway
1 of 2 did not go out. The release stands; nothing here failed the pipeline.
The exit code is zero either way. By the time this runs the release is public, and a red pipeline over a chat message is worse signal than a yellow one. One adapter failing does not stop the others: an announcement that did not reach Discord is no reason to withhold one from a mailing list.
Configuration¶
See announce in the release manifest
for the block, the when filter and why a webhook is named rather than
written.
In the pipeline¶
It belongs on the tag pipeline after the job that creates the release. It is
deliberately not part of release: an announcement that fails should not fail
a release that succeeded, and retrying one should not re-run the other.