Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/decisions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading