Skip to content

State the decision and not why the record exists, for records from now on - #305

Merged
iderex merged 1 commit into
mainfrom
docs/304-a-record-states-what-it-decides
Sep 5, 2026
Merged

State the decision and not why the record exists, for records from now on#305
iderex merged 1 commit into
mainfrom
docs/304-a-record-states-what-it-decides

Conversation

@iderex

@iderex iderex commented Sep 5, 2026

Copy link
Copy Markdown
Contributor

Closes #304

Beside the rules for a decision record, CONTRIBUTING.md now says that a record written from 2026-09-05 on states what it decides and does not explain why the record exists or speak about itself, that the records before that date keep their wording deliberately because the register forbids the edit, and hands the reader the command that lists them. docs/decisions/README.md points at that rule in one sentence and copies none of it.

git diff --stat origin/main...HEAD
 CONTRIBUTING.md           | 15 +++++++++++++++
 docs/decisions/README.md  |  2 ++
 2 files changed, 17 insertions(+)

git grep -nE "this (record|section) exists" HEAD -- docs/decisions/ | wc -l
12
git grep -nE "this (record|section) exists" HEAD -- . | wc -l
15

CORRECTED BY RE-RUNNING IT AFTER THE MERGE. The first version of this body pasted 13 beside the command scoped to docs/decisions/, and 13 is what the unscoped command returns; the register holds 12, the thirteenth is in src/server/address.rs. Both commands stand above with their own output now, at merge commit 9448d22fed1d94c94e52fafe4fb75b68c5565791.

The twelve in the register are unchanged by this change, on purpose: docs/decisions/0001-decision-records.md allows a typographical fix, the superseded-by half of a Status line and a pointer to a later record, and rewording is none of the three.

What this does not do

It adds no check. Nothing refuses the shape in a new record; the rule is prose and the review of the pull request that adds a record is where it is caught, and the text says so.

The means

Markdown in two documents the tree already carries; no language, runtime or dependency is added.

Nobody other than me has read this change.

…w on [#304]

A decision record here could open by saying what it exists to prevent, and
thirteen sentences of that shape stand in the register at origin/main
7587fa7, three found on 2026-08-09 and ten arrived since with new records.
The register's own rule forbids rewording a landed record, so those stay.
CONTRIBUTING.md now says, beside the rules for a record, that a record written
from 2026-09-05 on states what it decides without speaking about itself, that
the earlier ones keep their wording deliberately, and hands a reader the command
that lists them instead of a list that would go stale. docs/decisions/README.md
points at that rule in one sentence.

Closes #304

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
@iderex
iderex merged commit 9448d22 into main Sep 5, 2026
28 checks passed
@iderex
iderex deleted the docs/304-a-record-states-what-it-decides branch September 5, 2026 12:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A decision record states what it decides and not why the record exists, from now on

1 participant