punktfunk/docs/releases/README.md

Release notes

One file per stable release: docs/releases/vX.Y.Z.md. Its contents become the Gitea release body verbatim and are the source of the Discord #releases announcement.

Why this exists

Releases used to be created by CI with an empty body; the notes were pasted in by hand afterward. That left a window where the release — and anything announcing it — carried no notes. Now the notes are authored before the tag is pushed, as part of the version bump, so the release is born complete and the announcement always has something to say.

The flow

1. Write the notes. Add docs/releases/vX.Y.Z.md in the same commit (or PR) as the version bump. Copy TEMPLATE.md and fill it in. This file is the single source of truth for the body. Docs freshness, while you have the diff in front of you: every user-facing fact the release changes has its docs-site page updated (CONTRIBUTING.md "Where facts live" — docs-drift in CI catches renamed knobs and dead links, not a stale sentence). If an install command, repo URL or port changed, data/platforms.json changed with it — then run bun run sync-platforms in punktfunk-website and commit, because its download page vendors that file and only refreshes when someone does. Same pass for the website itself: does the landing page still describe what this release ships (features, platforms, the blog post the CMS expects per release)?
2. Tag & push. git tag -a vX.Y.Z … && git push origin vX.Y.Z fans out to the build workflows. Whichever one wins the create race seeds the release body from this file (scripts/ci/gitea-release.sh → ensure_release, and its PowerShell twin). The release page shows the notes immediately.
3. Wait for green. Let every platform's CI finish and go green.
4. Announce. Dispatch the announce workflow (.gitea/workflows/announce.yml) with the tag. It re-asserts this file over the live release (so any late edit wins) and posts an embed to Discord #releases. Pressing "go" is the quality gate — a half-built release is never announced. Stable-only; a -rc tag is refused unless allow_prerelease=true.

If a platform's run never appears, do not re-run the PR run — it cannot publish. A re-run replays the original event (pull_request), and android's publish steps are gated on a push, so they stay skipped no matter how often you press it. Merging two PRs seconds apart can leave the older merge sha with no run at all — Gitea attributes the window's runs to the newer head (2026-08-14: 1e5dca4c lost its run to b5cace3a, 12 s later), which is how an android change reaches main having never been built. Recover it by dispatching android.yml on that ref with publish=true; that is the only manual path reaching the registry and Play, and a plain dispatch stays build-only so a stray click can't ship to testers. Check for the gap by matching your own merge sha in the run list — "CI ran" is not the same as "your commit ran".

Editing the notes after the tag is fine: update this file, then re-run step 4 (or PATCH the body via the API) — the announce step always re-syncs from the file, so the file stays authoritative even across a tag re-point.

Canary / -rc builds have no file here on purpose: they get no curated body and are not announced.

Google Play "What's new": whatsnew/vX.Y.Z.txt

Play shows its own release notes on the Play Store listing and in the Play Store app, and caps them at 500 characters per language — the vX.Y.Z.md body is two orders of magnitude too long, so it gets its own short file: docs/releases/whatsnew/vX.Y.Z.txt.

Write it for a phone/TV user, not a host operator: only what changed in the Android app is worth their 500 characters. Plain text (Play renders no markdown), one • bullet per line, same voice rules as below. Copy whatsnew/TEMPLATE.txt.

A vX.Y.Z tag without this file fails the android job before it builds. This is a hard gate, not a warning, because the failure it prevents is silent: when the file is missing Play does not show an empty "What's new" — it carries the previous release's text onto the new version, so the store listing describes a build nobody is getting, and nothing surfaces that but reading the listing. It is the same shape as the v0.22.3 notes announcing a feature that release never contained. The gate also rejects a file byte-identical to another release's, which is that bug reached by copy-paste instead of by omission.

The gate runs first in the job, so a miss costs a second and leaves nothing half-published — no build, no assets on the Gitea release, nothing on Play. Two more checks sit downstream: play-upload.py refuses text over the 500-char cap (printing the real count) before it uploads, because the API only rejects oversized notes at commit, by which point the AAB is already on Play.

Canary is exempt: it has no curated notes; open-testing users see the previous release's text on a canary, which is cosmetic and cheaper than gating every main push on a notes file.

Same freeze rule as the notes: once the tag exists, this file is the record of what that versionCode shipped.

Voice & format

Write for the people who USE Punktfunk to stream their games and desktops — not for the people who build it. A non-engineer should finish knowing what's new and whether it affects them; an engineer should never be confused or forced to decode internals. (See any recent vX.Y.Z.md for the target.)

1. Lead with the benefit. Each entry = what the user can now do, what now works, or what stopped going wrong — in their words. Implementation is not the story.
2. No internal vocabulary in the body. No protocol/message names, code type names, hex codes or hardware IDs, crate/component names, or API symbols. Translate any essential detail to plain language. Name things users recognize (iPad, Apple Pencil, Steam Deck, Android TV, the Windows sign-in screen) — not subsystems.
3. Group as New / Improved / Fixed, each a bold one-line lead-in + a tight plain explanation. Skimmable. The lead-in text before the first ## is what the Discord announcement shows, so make it a real, plain-language summary.
4. Be specific and honest — no vague "various improvements"; a reader should know exactly what changed.
5. Compatibility line up top, in plain terms: can they update one side at a time? does their existing setup keep working? No version numbers in the lead.
6. No protocol / ABI / driver / embedder detail in this file at all. It goes in the root CHANGELOG.md (see below), and the notes carry a single short ## For developers section linking there. Nothing else in vX.Y.Z.md may use an internal name.
7. Open with a ## TL;DR — three to six bullets naming only what most readers would be sorry to miss, each one line. A large release is exactly where a reader gives up, and the TL;DR is what they read instead of giving up. If something needs the reader to act, it belongs here and in ## Before you update, not buried in ## Fixed.

The technical half: root CHANGELOG.md

Why it is separate. Through v0.24.0 the engineering detail lived in an ## Under the hood (for developers) section at the bottom of each release's notes. That worked while releases were small. It stopped working: v0.25.0 is 300+ commits, and the section had grown long enough to bury the user-facing half it was appended to — the exact failure the voice rules exist to prevent. The two audiences also want different shapes. A user reads one release and wants prose; an embedder wants to diff across releases and see when the ABI moved, which is a table, not a paragraph.

So: vX.Y.Z.md is for people who use Punktfunk, CHANGELOG.md is for people who build against it, and neither has to compromise for the other.

Format. Newest release first, one ## vX.Y.Z section each. Lead with a version table (wire protocol, C ABI, driver protocol, gamepad channel — every row, marked unchanged where it did not move, because "unchanged" is the answer an embedder most often needs). Then breaking changes, then whatever else matters: capability bits, new environment variables, wire additions, workspace members. Internal names are the point here — use them.

Linking. The notes link to the file at the tag, not at main: https://git.unom.io/unom/punktfunk/src/tag/vX.Y.Z/CHANGELOG.md. A release's notes are frozen; a link to main would silently start describing a later release.

Same freeze rule. Add the release's section in the version-bump commit, alongside the notes.

The short annotated-tag message stays separate and short (a headline + a paragraph); it is the tag object's message, not this file.