Repository navigation
docs(#8971): keep code-pinned links out of ADR bodies - #8972
Conversation
ADR reviews (0144, 0147-0149, 0151, 0152) kept flagging the same problems. Authors met the "cite current behavior" rule with line-pinned blob/<sha>#L links in Context and Decision, which turned ADRs into code tours that went stale. Decisions repeated sibling ADRs or normative contracts. Numbers had no stated basis. Series of ADRs landed out of step with each other. Claims about current behavior still have to be checked against the code at a commit SHA. The file/function evidence now goes in the PR description, and the ADR body describes the behavior in plain prose and links the PR, issue, or ADR that introduced it. - skills/writing-adrs/SKILL.md: reword checklist step 6; extend "Link, don't repeat" to cover sibling ADRs and docs/normative/ contracts; add Red Flags for numbers with no basis and for re-checking a series after a sibling merges; add Common Mistakes rows for line-pinned links, slugs that name a rejected option, and "Planned:" status blocks in Context. - docs/ADRs/0000-adr-template.md: update the Context prompt to match. - docs/contributing/adrs.md: reviewers check claims against the evidence in the PR description and flag line-pinned links in the ADR body. - AGENTS.md: reword the ADR row to match. Edits stay within step 6, "Link, don't repeat", Red Flags, and Common Mistakes, to keep conflicts small with open PRs #7356, #7428, #7676. Note: pre-commit could not fetch remote hook repos (TLS failure in the sandbox). The applicable hooks ran directly instead (pre-commit-hooks 6.0.0 fixers/checks, lint-adr-*, lint-docs-links, lint-broken-symlinks, lychee) and all passed. gitleaks was covered by scan-secrets. Closes #8971 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
/fs-fix-stop |
|
Fix agent disabled for this PR. Remove the |
Step 6, the template's Context prompt and the reviewer bullets each grew to four or five sentences; fold them back to two with the same rule. Ban every blob/<sha>/ code permalink in the ADR body, not only #L ones, since the old template's whole-file example had the same staleness problem. Restore that reading main is fine once its SHA is recorded. Assisted-by: Claude (fix), Claude (review) Signed-off-by: Wayne Sun <gsun@redhat.com>
Site previewPreview: https://0c393361-site.fullsend-ai.workers.dev Commit: |
|
🤖 Finished Review · ✅ Success · Started 4:51 PM UTC · Completed 5:04 PM UTC Commit: Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.60 |
|
<!-- fullsend:risk-assessment --> DetailsSmall documentation update aligning closely with the linked issue, elevated to moderate risk due to touching two protected paths (AGENTS.md and skills/) and moderate git churn on AGENTS.md. |
ReviewFindingsMedium
Labels: PR updates the writing-adrs skill and ADR contributing guidance. |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
…n rule The ADR guidance that merged in #8972 keeps file and function evidence out of ADR bodies: describe current behaviour in plain language, link the issue that records it, and put the code evidence at a commit SHA in the pull request description. Rewrite ADR 0156's Context paragraph that way. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Bill Murdock <bmurdock@redhat.com>
Summary
This updates the ADR authoring guidance in this repo: the
writing-adrsskill, the ADR template,docs/contributing/adrs.md, and the ADR row inAGENTS.md. Claims about current behaviour are still checked against the code at a commit SHA. The file or function evidence now goes in the PR description. The ADR body describes the behaviour in plain prose and links the PR, issue, or ADR that introduced it. The PR also adds the other lessons from reviewing recent ADRs (0144, 0147–0149, 0151, 0152).This revises the citation rule from #8490
#8491 (for #8490, approved by ifireball and rh-hemartin) told ADR authors to cite the implementing file or function at a commit SHA, and the template showed a
blob/<SHA>/...permalink as the example. This PR changes where that citation goes. It does not drop the check.main, and reviewers check it.blob/<sha>/path#L…permalinks are no longer allowed there.Because this revises guidance that #8491's reviewers approved, it needs their call before it merges.
Changes
skills/writing-adrs/SKILL.mdblob/<sha>/path#L…permalinks out of Context and Decision.docs/normative/contract (often in the same PR) defines a rule, link it in one line instead of restating it.docs/ADRs/0000-adr-template.md: the Context prompt now matches step 6.docs/contributing/adrs.md: reviewers check claims against the evidence in the PR description and flag code permalinks in the ADR body.AGENTS.md: the ADR row now matches the new rule.Edits stay within step 6, "Link, don't repeat", Red Flags, and Common Mistakes. #7428 merges cleanly with this branch. #7356 and #7676 already conflict with
main; this PR adds lines next to theirs indocs/contributing/adrs.mdandAGENTS.md, so their rebase gets one more small hunk.Testing
pre-commit run --from-ref origin/main --to-ref HEAD(whatmake lintruns, over the whole branch diff): every applicable hook passed, includinglint ADR statuses,lint ADR numbers,lint ADR frontmatter,lint docs link scope,lint markdown links,lint broken symlinksandDetect hardcoded secrets.Checklist
!for breaking changes)🤖 Generated with Claude Code
Closes #8971
Post-script verification
agent/8971-adr-code-links-guidance)12a09ace3e26b1e52442ee628ac570f794f856f6..HEAD)