From 3774826270b9bcacbc2d9e287e21e6632977daa4 Mon Sep 17 00:00:00 2001 From: Nils Lehnen <30603423+iderex@users.noreply.github.com> Date: Sat, 5 Sep 2026 14:06:54 +0200 Subject: [PATCH] State the decision and not why the record exists, for records from now 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 7587fa71, 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> --- CONTRIBUTING.md | 15 +++++++++++++++ docs/decisions/README.md | 2 ++ 2 files changed, 17 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b24102a..e7e2e39 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -447,6 +447,21 @@ The number of a record is the number of the issue whose decision it records, and `docs/decisions/README.md` lists every record. Adding a record without its index line leaves the index wrong and nothing here refuses 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. "The failure this record exists to +prevent" and "what this section exists for" are the shapes it does not use: a +sentence about the record's own presence tells a reader nothing that the +decision, the failure and the reversal condition do not already say. Records +that predate that date keep their wording deliberately. The register allows +three in-place edits and rewording is not one of them, so the sentences already +landed stay as they are, and which records carry one is derived rather than +listed here: + + git grep -nE "this (record|section) exists" -- docs/decisions/ + +Nothing refuses the shape in a new record. The rule is prose, and the review of +the pull request that adds the record is where it is caught. + ## Adding a check to the gate Where a check needs logic rather than one command, the logic goes in a script diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 01ecda2..b90f495 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -3,6 +3,8 @@ Every record here, by number and title. The shape a record takes, how numbers are allocated, and why a record is superseded rather than edited are in [0001. Decision records](0001-decision-records.md). +How a record written from 2026-09-05 on is worded, and why the ones before it keep +their wording, is under `## Decisions` in [CONTRIBUTING.md](../../CONTRIBUTING.md). - [0001. Decision records](0001-decision-records.md) - [0003. What the core does not do](0003-what-the-core-does-not-do.md)