#488 - docs(convention): CHANGELOG fragment style guide — skim-scan shape for adopters - frankenbit/release-toolkit

bosun commented

2026-07-11 12:03:59 +02:00

Owner

Motivation

Empirical anchor (2026-07-11, ember v0.3.0 release): the [0.3.0] CHANGELOG entries shipped in essay-length paragraphs — 400–1000 chars each, with internal jargon (§10.2b, "invariant-by-shape") and even a base64 anchor string (eyJrIjoi…) that visually reads like a partial credential leak. Operator flagged the shape as unreadable at skim-scan.

Root cause: the release-toolkit doesn't document what a good fragment looks like. PR contributors default to writing the full PR-body reasoning into the fragment, which then rides straight into CHANGELOG.md at release-cut time. The convention exists in the Keep-a-Changelog spec but isn't surfaced where contributors read fragment guidance.

Ask

Ship a CONTRIBUTING-fragment-style template (docs snippet or full docs/fragment-style.md — adopter-friendly shape) that adopters can point their contributors at from their own CONTRIBUTING.md / PR template / etc. Shape:

One bullet per fragment — not a paragraph
Lead with what the reader sees — the verb, behavior, or fix shipped
Parenthesize the internal ref — (#N) or (§X.Y) at end
Avoid team-internal jargon — unless it's the actual name of the thing shipped
Keep it skimmable — 1–2 lines, not a paragraph
Full-prose reasoning belongs in the PR body, not the changelog

Delivery

docs/fragment-style.md (or CONTRIBUTING.md section) with the above conventions + before/after examples (essay-length → skim-scan)
Cross-linked from the fragment-check workflow's error/warning output (so a contributor whose fragment fails validation sees a pointer to the style guide, not just "fragment missing")
Optional: lint check for fragment length (soft warning at >500 chars, hard fail at >2000?) — probably overkill; the style guide + review is enough

Verification AC

Style guide landed in docs/fragment-style.md (PR#490, +171 lines of substantive style content)
Adopter-facing pointer landed in README.md (PR#490, +7 lines)
Fragment-check workflow references style guide (PR#490, .forgejo/workflows/reusable-changelog-fragment-check.yml +12/-1)
Optional length linter DELIVERED same PR — not deferred to sub-tracker; scripts/fragment-check.sh +60 lines added the length-warn CI signal (PR#490 title: 'fragment style guide + length-warn CI signal')

ember v0.3.0 [0.3.0] essay-length CHANGELOG (fixed via ember#85)
release-toolkit#487 — template-drift class; different failure but same "silent drift on the CHANGELOG surface" family

Anchor

Empirical surfacing 2026-07-11 during ember v0.3.0 manual recovery
Filed by Bosun on operator standing approval per Ember Wave 3 arc

Discipline gap confirmed 2026-07-11 (v0.5.0 cut recovery)

Ember's v0.5.0 rolling PR again shipped essay-length fragments — same class as the v0.2.0 → v0.3.0 recovery that anchored this tracker. Bosun rewrote 9 fragments (60% length reduction, 6618 → 2611 chars) before merging the release; substrate-of-record captured at ember#115.

Cause: this tracker (release-toolkit#488) was filed but never delivered as substrate. Contributors default back to essay-shape without a live style guide.

Scope extension: mechanical length-warn

Beyond the style-guide doc, add a mechanical signal at PR time:

fragment-check workflow reports a warning (not hard-fail) when any fragment exceeds a soft threshold (proposed: ~500 chars)
The warning names the style guide + shows the offending file(s)
Threshold configurable via workflow input for consumer projects that want stricter/looser bounds
Does NOT block merge — the discipline is the contributor's + reviewer's; the warn is a cue

Priority elevated to medium — two documented v0.x release recoveries (v0.2.0 → v0.3.0 + v0.4.0 → v0.5.0) now anchor this class. Codified-not-embodied has real cost.

## Motivation Empirical anchor (2026-07-11, ember v0.3.0 release): the [0.3.0] CHANGELOG entries shipped in essay-length paragraphs — 400–1000 chars each, with internal jargon (§10.2b, "invariant-by-shape") and even a base64 anchor string (`eyJrIjoi…`) that visually reads like a partial credential leak. Operator flagged the shape as unreadable at skim-scan. Root cause: the release-toolkit doesn't document what a *good* fragment looks like. PR contributors default to writing the full PR-body reasoning into the fragment, which then rides straight into CHANGELOG.md at release-cut time. The convention exists in the Keep-a-Changelog spec but isn't surfaced where contributors read fragment guidance. ## Ask Ship a **CONTRIBUTING-fragment-style** template (docs snippet or full `docs/fragment-style.md` — adopter-friendly shape) that adopters can point their contributors at from their own CONTRIBUTING.md / PR template / etc. Shape: - **One bullet per fragment** — not a paragraph - **Lead with what the reader sees** — the verb, behavior, or fix shipped - **Parenthesize the internal ref** — `(#N)` or `(§X.Y)` at end - **Avoid team-internal jargon** — unless it's the actual name of the thing shipped - **Keep it skimmable** — 1–2 lines, not a paragraph - **Full-prose reasoning belongs in the PR body**, not the changelog ## Delivery - `docs/fragment-style.md` (or CONTRIBUTING.md section) with the above conventions + before/after examples (essay-length → skim-scan) - Cross-linked from the fragment-check workflow's error/warning output (so a contributor whose fragment fails validation sees a pointer to the style guide, not just "fragment missing") - Optional: lint check for fragment length (soft warning at >500 chars, hard fail at >2000?) — probably overkill; the style guide + review is enough ## Verification AC - [x] Style guide landed in `docs/fragment-style.md` (PR#490, +171 lines of substantive style content) - [x] Adopter-facing pointer landed in `README.md` (PR#490, +7 lines) - [x] Fragment-check workflow references style guide (PR#490, `.forgejo/workflows/reusable-changelog-fragment-check.yml` +12/-1) - [x] Optional length linter DELIVERED same PR — not deferred to sub-tracker; `scripts/fragment-check.sh` +60 lines added the length-warn CI signal (PR#490 title: 'fragment style guide + length-warn CI signal') ## Related - ember v0.3.0 [0.3.0] essay-length CHANGELOG (fixed via ember#85) - release-toolkit#487 — template-drift class; different failure but same "silent drift on the CHANGELOG surface" family ## Anchor - Empirical surfacing 2026-07-11 during ember v0.3.0 manual recovery - Filed by Bosun on operator standing approval per Ember Wave 3 arc --- ## Discipline gap confirmed 2026-07-11 (v0.5.0 cut recovery) Ember's v0.5.0 rolling PR again shipped essay-length fragments — same class as the v0.2.0 → v0.3.0 recovery that anchored this tracker. Bosun rewrote 9 fragments (60% length reduction, 6618 → 2611 chars) before merging the release; substrate-of-record captured at ember#115. **Cause**: this tracker (release-toolkit#488) was filed but never delivered as substrate. Contributors default back to essay-shape without a live style guide. ## Scope extension: mechanical length-warn Beyond the style-guide doc, add a mechanical signal at PR time: - `fragment-check` workflow reports a **warning** (not hard-fail) when any fragment exceeds a soft threshold (proposed: ~500 chars) - The warning names the style guide + shows the offending file(s) - Threshold configurable via workflow input for consumer projects that want stricter/looser bounds - Does NOT block merge — the discipline is the contributor's + reviewer's; the warn is a cue **Priority elevated to medium** — two documented v0.x release recoveries (v0.2.0 → v0.3.0 + v0.4.0 → v0.5.0) now anchor this class. Codified-not-embodied has real cost.

bosun added the

priority/low

size/S

kind/docs

labels

2026-07-11 12:03:59 +02:00

bosun added

and removed

labels

2026-07-12 19:46:37 +02:00

bosun commented

2026-07-13 07:23:58 +02:00

Author

Owner

Priority bumped from medium → high (2026-07-13, Bosun on operator direction).

Anchor: n=2 discipline slip on the same fragment-length pattern:

v0.5.0 cut (2026-07-12) — operator asked for CHANGELOG prose trim post-hoc; 9 fragments rewrote by Bosun with ~60% length reduction
v0.6.0 cut (2026-07-13) — same operator ask, again post-hoc; CHANGELOG trimmed to v0.3.0 skim-scan shape

The pattern is: fragments come in verbose because there's no rubric authors can check against at draft-time + no mechanical feedback loop. Two waves = codified-but-not-embodied gap is durable. Warrants moving up the queue over lower-priority items.

Deliverables (unchanged from original scope):

Docs style guide for fragment authors — explicit v0.3.0-shape rubric (1-3 lines per bullet, no paragraph explanations, format verb — what/why (#N))
Mechanical changelog-length-check CI gate — warn on fragments exceeding N lines, suggest trim

Reference cut for the target shape: ember v0.3.0 CHANGELOG — skim-scan bullets, section headers even when None..

**Priority bumped from medium → high** (2026-07-13, Bosun on operator direction). **Anchor**: n=2 discipline slip on the same fragment-length pattern: - **v0.5.0 cut** (2026-07-12) — operator asked for CHANGELOG prose trim post-hoc; 9 fragments rewrote by Bosun with ~60% length reduction - **v0.6.0 cut** (2026-07-13) — same operator ask, again post-hoc; CHANGELOG trimmed to v0.3.0 skim-scan shape The pattern is: fragments come in verbose because there's no rubric authors can check against at draft-time + no mechanical feedback loop. Two waves = codified-but-not-embodied gap is durable. Warrants moving up the queue over lower-priority items. **Deliverables (unchanged from original scope)**: 1. Docs style guide for fragment authors — explicit v0.3.0-shape rubric (1-3 lines per bullet, no paragraph explanations, format `verb — what/why (#N)`) 2. Mechanical `changelog-length-check` CI gate — warn on fragments exceeding N lines, suggest trim Reference cut for the target shape: [ember v0.3.0 CHANGELOG](https://git.frankenbit.de/frankenbit/ember/src/branch/main/CHANGELOG.md) — skim-scan bullets, section headers even when `None.`.