Skip to content

Commit b755f4c

Browse files
docs(governance): address PR #382 review nits (Henderson quote, MADR, Changelog)
- Henderson quote: restore verbatim two-sentence form ("In theory, immutability is ideal. In practice, mutability has worked better for our teams."). - MADR: correct the claim — MADR uses a single `date` field ("last updated"), not a last-updated date distinct from the decision date; note that this standard's two-field design (immutable `Date:` + separate `Last-updated:`) goes further. - Changelog template: make "omit when first creating" explicit so a freshly copied template doesn't ship a present-but-empty section. - Regenerate Starlight mirror. Refs #380 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent a9fc5e0 commit b755f4c

2 files changed

Lines changed: 4 additions & 4 deletions

File tree

docs/decisions/README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ What follows from this decision:
4545

4646
## Changelog
4747

48-
(Optional; present once the ADR has been refined in place. One dated bullet per refinement. The decision date in `**Date:**` is never overwritten.)
48+
(Optional; omit when first creating the ADR. Add this section on the first in-place refinement, one dated bullet per refinement. The decision date in `**Date:**` is never overwritten.)
4949

5050
- YYYY-MM-DD — What was refined and why (decision unchanged).
5151
```
@@ -82,7 +82,7 @@ Lifecycle state (above) is **orthogonal** to ordinary upkeep. Two different oper
8282
| Reverse the decision; choose a different approach; change what a reader must do | **Reversal** | New ADR with `**Supersedes:** ADR-NNN`; mark the old `**Superseded by:** ADR-MMM` | both change | new ADR gets its own `Date:` |
8383
| The decision no longer applies (context evaporated) | **Obsolescence** | Mark `deprecated`; note why | `deprecated` | bump `Last-updated:` |
8484

85-
This replaces strict immutability with the mainstream ADR practice. Joel Parker Henderson's widely-cited guidance notes that *"in theory, immutability is ideal; in practice, mutability has worked better for our teams"* — insert new information into the existing ADR with a date stamp and a note. MADR likewise tracks a last-updated date distinct from the decision date. The **decision date is never overwritten**; refinements are recorded in the `## Changelog` and the `Last-updated` field, keeping the record self-contained (an agent should not need to excavate git history to learn what was refined and when).
85+
This replaces strict immutability with the mainstream ADR practice. Joel Parker Henderson's widely-cited guidance notes that *"In theory, immutability is ideal. In practice, mutability has worked better for our teams."* — insert new information into the existing ADR with a date stamp and a note. MADR's template uses a single `date` field meaning "when the decision was last updated"; this standard goes further, keeping the decision `Date:` immutable and recording refinements separately. The **decision date is never overwritten**; refinements are recorded in the `## Changelog` and the `Last-updated` field, keeping the record self-contained (an agent should not need to excavate git history to learn what was refined and when).
8686

8787
## Relationship to `docs/design/`
8888

docs/src/content/docs/decisions/Readme.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ What follows from this decision:
4949

5050
## Changelog
5151

52-
(Optional; present once the ADR has been refined in place. One dated bullet per refinement. The decision date in `**Date:**` is never overwritten.)
52+
(Optional; omit when first creating the ADR. Add this section on the first in-place refinement, one dated bullet per refinement. The decision date in `**Date:**` is never overwritten.)
5353

5454
- YYYY-MM-DD — What was refined and why (decision unchanged).
5555
```
@@ -86,7 +86,7 @@ Lifecycle state (above) is **orthogonal** to ordinary upkeep. Two different oper
8686
| Reverse the decision; choose a different approach; change what a reader must do | **Reversal** | New ADR with `**Supersedes:** ADR-NNN`; mark the old `**Superseded by:** ADR-MMM` | both change | new ADR gets its own `Date:` |
8787
| The decision no longer applies (context evaporated) | **Obsolescence** | Mark `deprecated`; note why | `deprecated` | bump `Last-updated:` |
8888

89-
This replaces strict immutability with the mainstream ADR practice. Joel Parker Henderson's widely-cited guidance notes that *"in theory, immutability is ideal; in practice, mutability has worked better for our teams"* — insert new information into the existing ADR with a date stamp and a note. MADR likewise tracks a last-updated date distinct from the decision date. The **decision date is never overwritten**; refinements are recorded in the `## Changelog` and the `Last-updated` field, keeping the record self-contained (an agent should not need to excavate git history to learn what was refined and when).
89+
This replaces strict immutability with the mainstream ADR practice. Joel Parker Henderson's widely-cited guidance notes that *"In theory, immutability is ideal. In practice, mutability has worked better for our teams."* — insert new information into the existing ADR with a date stamp and a note. MADR's template uses a single `date` field meaning "when the decision was last updated"; this standard goes further, keeping the decision `Date:` immutable and recording refinements separately. The **decision date is never overwritten**; refinements are recorded in the `## Changelog` and the `Last-updated` field, keeping the record self-contained (an agent should not need to excavate git history to learn what was refined and when).
9090

9191
## Relationship to `docs/design/`
9292

0 commit comments

Comments
 (0)