State the decision and not why the record exists, for records from now on - #305
Merged
Merged
Conversation
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #304
Beside the rules for a decision record,
CONTRIBUTING.mdnow 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.mdpoints at that rule in one sentence and copies none of it.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 insrc/server/address.rs. Both commands stand above with their own output now, at merge commit9448d22fed1d94c94e52fafe4fb75b68c5565791.The twelve in the register are unchanged by this change, on purpose:
docs/decisions/0001-decision-records.mdallows 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.