You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 8e46e04
Browse filesBrowse the repository at this point in the historyBrowse files
docs(adr): keep the decision-history line optional and align FORMAT owners with the issue
Review repairs for #3744 wording: the Decision history line stays a permission, PR logs and status change-logs route to the umbrella issue, the 8 KB figure reads as an approximate upper aim, and the AGENTS.md qualifiers return with meaning-neutral compressions.
Copy file name to clipboardExpand all lines: docs/adr/FORMAT.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -36,19 +36,19 @@ Do not record these in an ADR. Send each to its owner:
36
36
- Implementation inventories and file maps: the registries, types, and gates that own them.
37
37
- Measurements: `docs/evidence/`.
38
38
- Rollout and migration plans: the package docs, the help, or the umbrella issue.
39
-
- PR logs and status change-logs: delete them. Git history keeps them.
39
+
- PR logs and status change-logs: the umbrella issue.
40
40
41
41
Do not repeat general repo guidance that `AGENTS.md` already gives.
42
42
43
43
## The record stays current
44
44
45
-
An ADR states the current truth. It is not a log of the discussion around the decision. If the direction really changed, add one dated "Decision history" line with its reason and a link.
45
+
An ADR states the current truth. It is not a log of the discussion around the decision. An optional dated "Decision history" line records a real change of direction. If the direction really changed, you may add one such line with its reason and a link.
46
46
47
47
## Before you amend
48
48
49
49
1. Check the current code against the decision the record intends to keep.
50
50
2. Check the code comments and issues that cite the record.
51
-
3. If the code changed on purpose: update the record to the new truth. Record the reason. Add a "Decision history" line when the direction changed.
51
+
3. If the code changed on purpose: update the record to the new truth. Record the reason. When the direction changed, you may add the optional "Decision history" line.
52
52
4. If the code drifted by mistake: record the drift in an issue. Keep the constraint in the record.
53
53
5. Preserve constraints that the code cannot show.
54
54
6. If you change a section name or a decision number, update the code citations that point at it.
@@ -63,6 +63,6 @@ An amendment that changes the modality, scope, or exceptions of an accepted deci
63
63
64
64
## Size and naming
65
65
66
-
Keep each ADR near 8 KB. Prefer less.
66
+
Keep ADRs short. Aim below about 8 KB.
67
67
68
68
Name files `NNNN-slug.md` in `docs/adr/`. Scan the directory and use the next number. Add a row to the index in `docs/adr/README.md`.
0 commit comments