mirror of
https://github.com/bitsocialnet/5chan.git
synced 2026-08-03 07:41:04 +02:00
docs(blotter): enforce plain-English wording for end users
Rewrite two release entries that leaked dev jargon (v0.7.4 "Pretext feed sizing" / "mobile scroll perf", v0.7.3 "compact account history") and tighten the release skill's Step 3 with a non-negotiable plain-English rule plus good/bad examples. Mirror the rule inline in AGENTS.md so agents editing the blotter outside the skill still see it.
This commit is contained in:
Tommaso Casaburi
@@ -61,10 +61,10 @@ Good examples:
|
||||
|
||||
### Step 3 — Write the blotter message
|
||||
|
||||
This is a **separate, shorter** summary used for the in-app blotter banner.
|
||||
This is a **separate, shorter** summary used for the in-app blotter banner. **The blotter is read by end users — non-developers — so every highlight must be understandable to someone who has never seen the code.** This rule is non-negotiable even for internal/infrastructure changes that make it into the blotter.
|
||||
|
||||
Rules:
|
||||
- Comma-separated key highlights, no full sentence
|
||||
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 ~60–80 characters after the version prefix
|
||||
- **Only genuinely novel or noteworthy items** — things a user would find interesting or exciting
|
||||
@@ -73,10 +73,27 @@ Rules:
|
||||
- Fewer strong items beat many weak items; 2–4 highlights is ideal
|
||||
- Lead with the most impressive item
|
||||
|
||||
Plain-English rules (apply always, no matter what):
|
||||
- Write for a user who has never read the code. Each highlight must be self-explanatory to a non-dev reader of 5chan.
|
||||
- No internal library or module names (e.g. "Pretext", "Zustand", "portless", "Vite", "oxlint"). Translate into the user-visible effect.
|
||||
- No dev shorthand: avoid "perf", "deps", "refactor", "impl", "selector", "reducer", "hook", "a11y", "i18n", "DX", "CI", "CD", "lint", "typecheck".
|
||||
- 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.
|
||||
- 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, multi-provider uploads, mod queue redesign, catalog sorting"
|
||||
- "Syncs board dirs from GitHub, macOS icon, reply perf"
|
||||
- "Quote links, backlinks, pseudonymityMode, release artifacts"
|
||||
- "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"
|
||||
|
||||
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.
|
||||
|
||||
Save this string — you will pass it to the blotter script in Step 6.
|
||||
|
||||
|
||||
@@ -61,10 +61,10 @@ Good examples:
|
||||
|
||||
### Step 3 — Write the blotter message
|
||||
|
||||
This is a **separate, shorter** summary used for the in-app blotter banner.
|
||||
This is a **separate, shorter** summary used for the in-app blotter banner. **The blotter is read by end users — non-developers — so every highlight must be understandable to someone who has never seen the code.** This rule is non-negotiable even for internal/infrastructure changes that make it into the blotter.
|
||||
|
||||
Rules:
|
||||
- Comma-separated key highlights, no full sentence
|
||||
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 ~60–80 characters after the version prefix
|
||||
- **Only genuinely novel or noteworthy items** — things a user would find interesting or exciting
|
||||
@@ -73,10 +73,27 @@ Rules:
|
||||
- Fewer strong items beat many weak items; 2–4 highlights is ideal
|
||||
- Lead with the most impressive item
|
||||
|
||||
Plain-English rules (apply always, no matter what):
|
||||
- Write for a user who has never read the code. Each highlight must be self-explanatory to a non-dev reader of 5chan.
|
||||
- No internal library or module names (e.g. "Pretext", "Zustand", "portless", "Vite", "oxlint"). Translate into the user-visible effect.
|
||||
- No dev shorthand: avoid "perf", "deps", "refactor", "impl", "selector", "reducer", "hook", "a11y", "i18n", "DX", "CI", "CD", "lint", "typecheck".
|
||||
- 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.
|
||||
- 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, multi-provider uploads, mod queue redesign, catalog sorting"
|
||||
- "Syncs board dirs from GitHub, macOS icon, reply perf"
|
||||
- "Quote links, backlinks, pseudonymityMode, release artifacts"
|
||||
- "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"
|
||||
|
||||
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.
|
||||
|
||||
Save this string — you will pass it to the blotter script in Step 6.
|
||||
|
||||
|
||||
@@ -61,10 +61,10 @@ Good examples:
|
||||
|
||||
### Step 3 — Write the blotter message
|
||||
|
||||
This is a **separate, shorter** summary used for the in-app blotter banner.
|
||||
This is a **separate, shorter** summary used for the in-app blotter banner. **The blotter is read by end users — non-developers — so every highlight must be understandable to someone who has never seen the code.** This rule is non-negotiable even for internal/infrastructure changes that make it into the blotter.
|
||||
|
||||
Rules:
|
||||
- Comma-separated key highlights, no full sentence
|
||||
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 ~60–80 characters after the version prefix
|
||||
- **Only genuinely novel or noteworthy items** — things a user would find interesting or exciting
|
||||
@@ -73,10 +73,27 @@ Rules:
|
||||
- Fewer strong items beat many weak items; 2–4 highlights is ideal
|
||||
- Lead with the most impressive item
|
||||
|
||||
Plain-English rules (apply always, no matter what):
|
||||
- Write for a user who has never read the code. Each highlight must be self-explanatory to a non-dev reader of 5chan.
|
||||
- No internal library or module names (e.g. "Pretext", "Zustand", "portless", "Vite", "oxlint"). Translate into the user-visible effect.
|
||||
- No dev shorthand: avoid "perf", "deps", "refactor", "impl", "selector", "reducer", "hook", "a11y", "i18n", "DX", "CI", "CD", "lint", "typecheck".
|
||||
- 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.
|
||||
- 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, multi-provider uploads, mod queue redesign, catalog sorting"
|
||||
- "Syncs board dirs from GitHub, macOS icon, reply perf"
|
||||
- "Quote links, backlinks, pseudonymityMode, release artifacts"
|
||||
- "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"
|
||||
|
||||
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.
|
||||
|
||||
Save this string — you will pass it to the blotter script in Step 6.
|
||||
|
||||
|
||||
@@ -153,6 +153,7 @@ src/
|
||||
|
||||
- If `CHANGELOG.md` or package version changes, run `yarn blotter:check`.
|
||||
- If blotter check fails for missing release coverage, add a concise one-line release entry.
|
||||
- Blotter entries are shown to 5chan end users, not developers. Every release message must be plain English a non-dev can understand: no internal library names (e.g. `Pretext`, `Zustand`), no dev shorthand (`perf`, `deps`, `refactor`, `a11y`, `CI`), no file paths, and no PR numbers. Prefer user-visible outcomes over implementation details (`performant account history`, not `compact account history`). Broad wording like `security fix`, `stability fixes`, or `bug fixes` is fine when the change is hard to summarize. Full rules and examples live in the `release` skill's Step 3.
|
||||
- Ignore manual entries for release coverage logic.
|
||||
- Use `yarn blotter` / `yarn blotter:manual` for manual dev messages.
|
||||
|
||||
|
||||
@@ -4,14 +4,14 @@
|
||||
"id": "release-0.7.4",
|
||||
"kind": "release",
|
||||
"timestamp": 1775736000,
|
||||
"message": "v0.7.4: Pretext feed sizing, mobile scroll perf, Android USB dev preview",
|
||||
"message": "v0.7.4: Smoother feed sizing, smoother mobile scrolling, Android USB dev preview",
|
||||
"version": "0.7.4"
|
||||
},
|
||||
{
|
||||
"id": "release-0.7.3",
|
||||
"kind": "release",
|
||||
"timestamp": 1774008000,
|
||||
"message": "v0.7.3: In-app desktop updates, opt-in thread auto-refresh, compact account history",
|
||||
"message": "v0.7.3: In-app desktop updates, opt-in thread auto-refresh, performant account history",
|
||||
"version": "0.7.3"
|
||||
},
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user