feat(adr)!: adr check reads only the Decision issues list

hexajon commented

2026-09-27 01:47:54 +00:00

Owner

A decision record is a file under docs/decisions/. adr check now reads only the issues in its "Decision issues:" list, under "## More Information". Every other issue link in a decision record is context for the reader, and adr check ignores it. This decision is in #634, and ADR 0045 records it with the status proposed.

The rules for the list:

A decision record with no "Decision issues:" list fails adr check.
A decided record has the status accepted, rejected, deprecated, or superseded. If a decided record has no issue to list, its author writes the one line "Decision issues: none - ". That line needs a reason, and a proposed record cannot use it.
In a proposed record, each listed issue must be open. The list must name an issue in the record's own repo, and in each repo in the impacts key of its front matter. The git config key madtea.adr.topLevelRepo can name another repo in place of the record's own repo.
In a decided record, each listed issue must be closed, with a comment that names the record's file name without ".md".
A fault in the list itself is a fault in the file: for example, a missing list, a none line with no reason, or a none line in a proposed record. So adr check reports it with --skip-remote-issues too. That flag skips only the read of the listed issues on the forge.

Other changes:

adr init writes record 0000 with the line "Decision issues: none - written by adr init to adopt MADR". So a tree fresh from adr init passes adr check with no forge access.
adr new --decision-issues replaces --tracking, and the madt_adr parameter decision_issues replaces tracking.
adr check names each rule by a plain name, such as decision-issues, and no longer by a code.
In this repo, 12 of the 44 existing decision records get a list of the issues that adr check read before. The other 32 get "Decision issues: none - recorded before this list existed".

BREAKING CHANGE: adr check fails every decision record that has no "Decision issues:" list, so each existing docs/decisions/ tree must add a list to each record. adr new --tracking and the madt_adr parameter tracking are removed, with no alias. adr check output names each rule by its plain name, not by its code.

Refs #634

A decision record is a file under docs/decisions/. adr check now reads only the issues in its "Decision issues:" list, under "## More Information". Every other issue link in a decision record is context for the reader, and adr check ignores it. This decision is in #634, and ADR 0045 records it with the status proposed. The rules for the list: - A decision record with no "Decision issues:" list fails adr check. - A decided record has the status accepted, rejected, deprecated, or superseded. If a decided record has no issue to list, its author writes the one line "Decision issues: none - <reason>". That line needs a reason, and a proposed record cannot use it. - In a proposed record, each listed issue must be open. The list must name an issue in the record's own repo, and in each repo in the impacts key of its front matter. The git config key madtea.adr.topLevelRepo can name another repo in place of the record's own repo. - In a decided record, each listed issue must be closed, with a comment that names the record's file name without ".md". - A fault in the list itself is a fault in the file: for example, a missing list, a none line with no reason, or a none line in a proposed record. So adr check reports it with --skip-remote-issues too. That flag skips only the read of the listed issues on the forge. Other changes: - adr init writes record 0000 with the line "Decision issues: none - written by adr init to adopt MADR". So a tree fresh from adr init passes adr check with no forge access. - adr new --decision-issues replaces --tracking, and the madt_adr parameter decision_issues replaces tracking. - adr check names each rule by a plain name, such as decision-issues, and no longer by a code. - In this repo, 12 of the 44 existing decision records get a list of the issues that adr check read before. The other 32 get "Decision issues: none - recorded before this list existed". BREAKING CHANGE: adr check fails every decision record that has no "Decision issues:" list, so each existing docs/decisions/ tree must add a list to each record. adr new --tracking and the madt_adr parameter tracking are removed, with no alias. adr check output names each rule by its plain name, not by its code. Refs #634

hexajon added 1 commit

2026-09-27 01:47:55 +00:00

feat(adr)!: adr check reads only the Decision issues list

ci / mcp-conformance (pull_request) Successful in 2m11s

Details

drift / govulncheck (pull_request) Has been skipped

Details

drift / forgejo-smoke (pull_request) Has been skipped

Details

drift / surface-diff (pull_request) Successful in 57s

Details

drift / forgejo-smoke (push) Has been skipped

Details

ci / mcp-conformance (push) Successful in -5s

Details

drift / govulncheck (push) Has been skipped

Details

drift / surface-diff (push) Successful in -11s

Details

ci / gate (push) Successful in 11m48s

Details

ci / gate (pull_request) Successful in 21m36s

Details

f6fc22930b

A decision record is a file under docs/decisions/. adr check now reads only the issues in its "Decision issues:" list, under "## More Information". Every other issue link in a decision record is context for the reader, and adr check ignores it. This decision is in #634, and ADR 0045 records it with the status proposed.

The rules for the list:

- A decision record with no "Decision issues:" list fails adr check.
- A decided record has the status accepted, rejected, deprecated, or superseded. If a decided record has no issue to list, its author writes the one line "Decision issues: none - <reason>". That line needs a reason, and a proposed record cannot use it.
- In a proposed record, each listed issue must be open. The list must name an issue in the record's own repo, and in each repo in the impacts key of its front matter. The git config key madtea.adr.topLevelRepo can name another repo in place of the record's own repo.
- In a decided record, each listed issue must be closed, with a comment that names the record's file name without ".md".
- A fault in the list itself is a fault in the file: for example, a missing list, a none line with no reason, or a none line in a proposed record. So adr check reports it with --skip-remote-issues too. That flag skips only the read of the listed issues on the forge.

Other changes:

- adr init writes record 0000 with the line "Decision issues: none - written by adr init to adopt MADR". So a tree fresh from adr init passes adr check with no forge access.
- adr new --decision-issues replaces --tracking, and the madt_adr parameter decision_issues replaces tracking.
- adr check names each rule by a plain name, such as decision-issues, and no longer by a code.
- In this repo, 12 of the 44 existing decision records get a list of the issues that adr check read before. The other 32 get "Decision issues: none - recorded before this list existed".

BREAKING CHANGE: adr check fails every decision record that has no "Decision issues:" list, so each existing docs/decisions/ tree must add a list to each record. adr new --tracking and the madt_adr parameter tracking are removed, with no alias. adr check output names each rule by its plain name, not by its code.

Refs #634

hexajon merged commit f6fc22930b into main

2026-09-27 01:48:01 +00:00

hexajon deleted branch issue-634-decision-issues-list

2026-09-27 01:48:02 +00:00

hexajon referenced this pull request

2026-09-28 18:16:43 +00:00

decision: move the ADR tooling into its own Go module, or keep it in madtea and improve it? #643

hexajon referenced this pull request

2026-09-28 18:45:41 +00:00

style: apply the gopls quick fixes and fix their stale comments #644

~~hexajon referenced this pull request 2026-09-29 19:31:31 +00:00~~