Release notes should be a list, not an essay: the reasoning belongs in the issue #254

New issue

Closed

opened 2026-09-17 14:08:43 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-09-17 14:08:43 +00:00

Owner

The 0.3.0 release notes are 47,562 words. That is four hours of reading, published as
the answer to "what changed?", and it is not a slip — it is what the convention asks for.

CHANGELOG.md is 58,734 words and 0.3.0 is 81% of it. One hundred and fifty-four entries,
averaging around three hundred words each, several running past a thousand. The release
workflow "creates the Forgejo release with the changelog section as its notes"
(CONTRIBUTING.md), so the section is the release page, verbatim, and nobody arriving at
a new version can find out in under a minute whether it affects them.

How it got that way

CLAUDE.md says an entry "says why, not what", and ends "with the issue it closes". The
first half of that rule was followed and the second half wasted. Every entry explains the
threat model, the alternative that was rejected and the thing that broke — and then names
the issue where all of that already is, in more detail, with the code beside it.

The rule is right about entries in the repository's history, which is where the phrase
comes from. It is wrong about release notes, and nothing distinguished the two because
they are the same text.

What the convention should be

A release note is one line: what changed, who it affects, and the issue number. The
issue carries the reasoning, the rejected alternatives and the detail. That is what issues
are for, they are already written, and every entry already links to one.

Security keeps room for a sentence of consequence — an operator needs to know whether to
hurry — but the analysis stays in the issue and, where there is one, the advisory.
A breaking change keeps the line that says what to do about it. That is an instruction,
not an explanation.
Everything else is a line. - Companies can be filtered by column. (#173)

Roughly: a hundred and fifty lines somebody can scan in two minutes, in place of forty-
seven thousand words nobody will read.

What to change

CLAUDE.md — the paragraph at the feature-ships-with rule. Say the length: one line,
ending in its issue; say why, not what, belongs in the issue and the commit message.
CONTRIBUTING.md — the release steps, same rule, so a human contributor reads it too.
tests/test_changelog.py — it already guards the shape of the file (sections, marks,
dates, that the notes tool can still slice a section out). It could guard this: every
entry ends with (#N), and no entry exceeds a stated length. A convention nobody checks
is the habit that produced 0.3.0.

What about what is already written

0.3.0 is published and the words are not wrong, only misplaced — leaving it is defensible.
The alternative is to condense 0.3.0 to its lines and keep the prose somewhere it belongs,
which is a day's work and worth doing only if the long-form text is wanted as a release
announcement or a wiki page. Unreleased should follow the new rule from the first entry
after this lands, whichever way that goes.

The 0.3.0 release notes are **47,562 words**. That is four hours of reading, published as the answer to "what changed?", and it is not a slip — it is what the convention asks for. `CHANGELOG.md` is 58,734 words and 0.3.0 is 81% of it. One hundred and fifty-four entries, averaging around three hundred words each, several running past a thousand. The release workflow "creates the Forgejo release with the changelog section as its notes" (`CONTRIBUTING.md`), so the section *is* the release page, verbatim, and nobody arriving at a new version can find out in under a minute whether it affects them. ## How it got that way `CLAUDE.md` says an entry "says why, not what", and ends "with the issue it closes". The first half of that rule was followed and the second half wasted. Every entry explains the threat model, the alternative that was rejected and the thing that broke — and then names the issue where all of that already is, in more detail, with the code beside it. The rule is right about *entries in the repository's history*, which is where the phrase comes from. It is wrong about release notes, and nothing distinguished the two because they are the same text. ## What the convention should be **A release note is one line: what changed, who it affects, and the issue number.** The issue carries the reasoning, the rejected alternatives and the detail. That is what issues are for, they are already written, and every entry already links to one. - Security keeps room for a sentence of consequence — *an operator needs to know whether to hurry* — but the analysis stays in the issue and, where there is one, the advisory. - A breaking change keeps the line that says what to do about it. That is an instruction, not an explanation. - Everything else is a line. `- Companies can be filtered by column. (#173)` Roughly: a hundred and fifty lines somebody can scan in two minutes, in place of forty- seven thousand words nobody will read. ## What to change - **`CLAUDE.md`** — the paragraph at the feature-ships-with rule. Say the length: one line, ending in its issue; say why, not what, belongs in the issue and the commit message. - **`CONTRIBUTING.md`** — the release steps, same rule, so a human contributor reads it too. - **`tests/test_changelog.py`** — it already guards the shape of the file (sections, marks, dates, that the notes tool can still slice a section out). It could guard this: every entry ends with `(#N)`, and no entry exceeds a stated length. A convention nobody checks is the habit that produced 0.3.0. ## What about what is already written 0.3.0 is published and the words are not wrong, only misplaced — leaving it is defensible. The alternative is to condense 0.3.0 to its lines and keep the prose somewhere it belongs, which is a day's work and worth doing only if the long-form text is wanted as a release announcement or a wiki page. **Unreleased** should follow the new rule from the first entry after this lands, whichever way that goes.

tiagoagueda added this to the 0.4.0 milestone

2026-09-17 14:08:43 +00:00

tiagoagueda added the

enhancement

documentation

labels

2026-09-17 14:08:43 +00:00

tiagoagueda referenced this issue

2026-09-17 14:12:58 +00:00

docs/PLAN.md has not been revised since before 0.3.0 and now says untrue things #255

tiagoagueda referenced this issue from a commit

2026-09-19 11:35:25 +00:00