docs(blotter): keep release highlights user-facing

This commit is contained in:
Tommaso Casaburi
2026-05-21 17:50:00 +07:00
parent f22c53ec1c
commit 67ddaee673
7 changed files with 28 additions and 22 deletions
+8 -6
View File
@@ -56,7 +56,7 @@ Rules:
- End with a period
Good examples:
- "This version adds backlinks for quoted posts, a copy user ID menu item, and several bug fixes."
- "This version adds backlinks for quoted posts, a copy user ID menu item, and clearer reply previews."
- "This release adds pseudonymity mode support per-reply and fixes timezone display issues."
### Step 3 — Write the blotter message
@@ -66,11 +66,12 @@ This is a **separate, shorter** summary used for the in-app blotter banner. **Th
Format rules:
- Comma-separated key highlights, each a short plain-English phrase (not a full sentence)
- Omit "This version..." prefix — the blotter script prepends `vX.Y.Z: ` automatically
- Aim for ~6080 characters after the version prefix
- Aim for ~4570 characters after the version prefix
- **Only genuinely novel or noteworthy items** — things a user would find interesting or exciting
- Skip regression fixes (restoring something that previously worked), routine bug fixes, minor z-index/modal/layout tweaks, test improvements, CI changes, and anything that isn't a new capability or a significant user-facing improvement
- Skip regression fixes (restoring something that previously worked), routine bug fixes, invisible security/stability work, minor z-index/modal/layout tweaks, test improvements, CI changes, and anything that isn't a new capability or a significant user-facing improvement
- If something was already a known feature and just got fixed/restored, it does not belong in the blotter
- Fewer strong items beat many weak items; 24 highlights is ideal
- Fewer strong items beat many weak items; 13 highlights is ideal
- If there are no genuinely interesting user-facing changes, do not invent filler highlights
- Lead with the most impressive item
Plain-English rules (apply always, no matter what):
@@ -80,20 +81,21 @@ Plain-English rules (apply always, no matter what):
- No codebase-only identifiers, file paths, component names, or PR numbers.
- Prefer the user-visible *outcome* over the mechanism. Example: "compact account history" (describes the code) → "performant account history" (describes what the user gets).
- Phrases must read as natural plain English. If a highlight needs a developer to explain it, rewrite it.
- Broad, general wording is fine when the change is broad or not easy to summarize (e.g. "security fix", "bug fixes", "stability fixes") — that's better than leaking jargon.
- Avoid broad maintenance labels like "security fixes", "bug fixes", or "stability fixes"; they are usually invisible, redundant, and dull. Only mention security or stability work when the user can perceive the outcome, and phrase it as that outcome.
- Okay to name concrete user-visible features/areas: "Board pagination", "Video auto-unmute setting", "File upload improvements", "Archive page", "Spoiler tags", "Catalog search".
Good examples (the part **you** write, without the `vX.Y.Z:` prefix):
- "Board pagination, file upload improvements, mod queue redesign, catalog sorting"
- "Video auto-unmute setting, platform info on homepage, faster board previews"
- "In-app desktop updates, opt-in thread auto-refresh, performant account history"
- "Quote references in replies, post backlinks, security fix"
- "Quote references in replies, post backlinks"
Bad examples (and why):
- "Pretext feed sizing" — names an internal library; user has no idea what this is.
- "Mobile scroll perf" — "perf" is dev shorthand; say "smoother mobile scrolling".
- "Compact account history" — describes the implementation; "performant account history" describes what the user gets.
- "Refactor subplebbit selectors" — three dev terms in a row; rewrite or drop.
- "Security fixes" — generic maintenance label; invisible to regular users and not interesting to read.
Save this string — you will pass it to the blotter script in Step 6.