docs(release): rewrite v0.19.0 notes for end users + set end-user notes voice
ci / web (push) Successful in 1m4s
ci / docs-site (push) Successful in 1m8s
apple / swift (push) Successful in 1m22s
decky / build-publish (push) Successful in 36s
docker / build-push (--build-arg FEDORA_VERSION=44, ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora44-rpm) (push) Successful in 15s
docker / build-push (., web/Dockerfile, punktfunk-web) (push) Successful in 14s
docker / build-push (ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora-rpm) (push) Successful in 15s
apple / screenshots (push) Successful in 6m29s
docker / build-push (ci, ci/rust-ci-noble.Dockerfile, punktfunk-rust-ci-noble) (push) Successful in 5m1s
ci / bench (push) Successful in 8m1s
docker / build-push (docs-site, docs-site/Dockerfile, punktfunk-docs) (push) Successful in 18s
deb / build-publish-host (push) Successful in 10m19s
deb / build-publish (push) Successful in 12m13s
android / android (push) Successful in 13m20s
docker / build-push (ci, ci/rust-ci.Dockerfile, punktfunk-rust-ci) (push) Successful in 6m26s
docker / deploy-docs (push) Successful in 24s
arch / build-publish (push) Successful in 16m53s
ci / rust (push) Successful in 25m37s
rpm / build-publish (44, fedora-44, punktfunk-fedora44-rpm) (push) Successful in 14m52s
rpm / build-publish (43, bazzite, punktfunk-fedora-rpm) (push) Successful in 18m8s
ci / web (push) Successful in 1m4s
ci / docs-site (push) Successful in 1m8s
apple / swift (push) Successful in 1m22s
decky / build-publish (push) Successful in 36s
docker / build-push (--build-arg FEDORA_VERSION=44, ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora44-rpm) (push) Successful in 15s
docker / build-push (., web/Dockerfile, punktfunk-web) (push) Successful in 14s
docker / build-push (ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora-rpm) (push) Successful in 15s
apple / screenshots (push) Successful in 6m29s
docker / build-push (ci, ci/rust-ci-noble.Dockerfile, punktfunk-rust-ci-noble) (push) Successful in 5m1s
ci / bench (push) Successful in 8m1s
docker / build-push (docs-site, docs-site/Dockerfile, punktfunk-docs) (push) Successful in 18s
deb / build-publish-host (push) Successful in 10m19s
deb / build-publish (push) Successful in 12m13s
android / android (push) Successful in 13m20s
docker / build-push (ci, ci/rust-ci.Dockerfile, punktfunk-rust-ci) (push) Successful in 6m26s
docker / deploy-docs (push) Successful in 24s
arch / build-publish (push) Successful in 16m53s
ci / rust (push) Successful in 25m37s
rpm / build-publish (44, fedora-44, punktfunk-fedora44-rpm) (push) Successful in 14m52s
rpm / build-publish (43, bazzite, punktfunk-fedora-rpm) (push) Successful in 18m8s
Release notes were written for the people who build Punktfunk, not the people who use it — dense with protocol/ABI/type names that confused even technical readers. Rewrite v0.19.0 in a benefit-first, plain-language voice (New/Improved/Fixed) with all internal terms removed from the body and every protocol/ABI/embedder detail moved to a single bottom "Under the hood" section. docs/releases/README.md now codifies this voice as the format spec for all future notes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
+20
-7
@@ -31,15 +31,28 @@ even across a tag re-point.
|
||||
Canary / `-rc` builds have **no** file here on purpose: they get no curated body and are not
|
||||
announced.
|
||||
|
||||
## Format
|
||||
## Voice & format
|
||||
|
||||
Match the house style (see any recent `vX.Y.Z.md`):
|
||||
**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.)
|
||||
|
||||
- Open with a **wire-compatibility** line — *"Wire-compatible with X.Y.x — existing pairings and
|
||||
clients keep working."* — plus a one-sentence fallback/negotiation note. This lead-in (all text
|
||||
before the first `##` header) is what the Discord embed shows, so make it a real summary.
|
||||
- Then `## Section` headers grouping the changes, with **bold lead-in** bullets.
|
||||
- Be concrete: env vars, ABI/protocol versions, on-glass-verified hardware, platform scope.
|
||||
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. **All protocol / ABI / driver / embedder detail goes in ONE `## Under the hood (for developers)`
|
||||
section at the very bottom** — the only place internal names and version numbers belong, clearly
|
||||
optional. The old dense engineering style survives only there.
|
||||
|
||||
The short annotated-**tag** message stays separate and short (a headline + a paragraph); it is the
|
||||
tag object's message, not this file.
|
||||
|
||||
Reference in New Issue
Block a user