From d4817334ad879bcbe12eafe502c54958d5c44a9e Mon Sep 17 00:00:00 2001 From: Angelica Willianto Date: Thu, 3 Sep 2026 11:39:15 +0800 Subject: [PATCH 1/2] docs(rules): tell if a PR's comments were handled before merge --- docs/rules/DEV-450.md | 41 +++++++++++++++++++++++++++++++++++++++++ docs/rules/README.md | 1 + 2 files changed, 42 insertions(+) create mode 100644 docs/rules/DEV-450.md diff --git a/docs/rules/DEV-450.md b/docs/rules/DEV-450.md new file mode 100644 index 0000000..779eea4 --- /dev/null +++ b/docs/rules/DEV-450.md @@ -0,0 +1,41 @@ +--- +id: DEV-450 +title: "Resolve Every Inline Thread Before Merging" +status: "active" +enforcement: "manual" +severity: "error" +depends_on: ["DEV-365"] +--- + +## Problem + +A PR merges with its inline threads still open. The reviewer cannot tell whether +each comment was fixed, answered, or ignored, and nothing in the record says +which. + +## Solution + +Each inline thread is a question the reviewer asked. Only the author knows +whether it was answered, so the author closes it, and closes it with the answer +in view. Resolving a thread in silence leaves the same gap as leaving it open: +the next reader still has to reconstruct what happened. + +1. Reply on the thread naming what changed, before resolving it. One sentence + is enough. +1. Resolve the thread yourself once that reply is posted. +1. When the fix landed outside this PR, name where: the other PR, the linked + Problem, or a follow-up issue, each by number. +1. Leave a thread open when you disagree with it. Answer it and let the + reviewer decide, per [DEV-410](./DEV-410.md). +1. Merge only when no thread is left open. + +```md +Good: fixed in 4a1c2f0, the heading is now `###`. [Resolve] Bad: [Resolve] +``` + +### Acceptance Criteria + +- [ ] Every inline thread on the PR is resolved or explicitly left open at merge +- [ ] Each resolved thread carries a reply naming what changed +- [ ] A fix made outside this PR names where it landed, by number +- [ ] No thread is resolved without a reply diff --git a/docs/rules/README.md b/docs/rules/README.md index 8bd6bab..b9df4e0 100644 --- a/docs/rules/README.md +++ b/docs/rules/README.md @@ -91,6 +91,7 @@ How to review, and the quality bar work is held to. - [DEV-420](./DEV-420.md): scout open PRs when idle - [DEV-430](./DEV-430.md): deliver bug-free work; review is a safety check - [DEV-440](./DEV-440.md): judge work by value delivered, not effort spent +- [DEV-450](./DEV-450.md): resolve every inline thread before merging ### 5. Advocacy From 93eab98e67eacb81b8edcb95880dde9631f16728 Mon Sep 17 00:00:00 2001 From: Angelica Willianto Date: Thu, 3 Sep 2026 11:59:45 +0800 Subject: [PATCH 2/2] docs(rules): read a thread's answer, not just its resolved mark --- docs/rules/DEV-450.md | 39 ++++++++++++++++++--------------------- docs/rules/README.md | 2 +- 2 files changed, 19 insertions(+), 22 deletions(-) diff --git a/docs/rules/DEV-450.md b/docs/rules/DEV-450.md index 779eea4..8a63007 100644 --- a/docs/rules/DEV-450.md +++ b/docs/rules/DEV-450.md @@ -1,6 +1,6 @@ --- id: DEV-450 -title: "Resolve Every Inline Thread Before Merging" +title: "Resolve Every Inline Thread With Its Answer" status: "active" enforcement: "manual" severity: "error" @@ -9,33 +9,30 @@ depends_on: ["DEV-365"] ## Problem -A PR merges with its inline threads still open. The reviewer cannot tell whether -each comment was fixed, answered, or ignored, and nothing in the record says -which. +A reviewer cannot tell whether the author fixed, answered, or ignored the +comments on a merged PR. A real objection ships and nobody notices. ## Solution -Each inline thread is a question the reviewer asked. Only the author knows -whether it was answered, so the author closes it, and closes it with the answer -in view. Resolving a thread in silence leaves the same gap as leaving it open: -the next reader still has to reconstruct what happened. +Each inline thread is a question the reviewer asked. Only the author knows the +answer, so the author writes it on the thread before closing it. Resolving marks +the thread settled; the reply carries the answer. -1. Reply on the thread naming what changed, before resolving it. One sentence - is enough. -1. Resolve the thread yourself once that reply is posted. -1. When the fix landed outside this PR, name where: the other PR, the linked - Problem, or a follow-up issue, each by number. -1. Leave a thread open when you disagree with it. Answer it and let the - reviewer decide, per [DEV-410](./DEV-410.md). -1. Merge only when no thread is left open. +1. Reply to every inline thread before you merge, and name what changed. One + sentence is enough. +1. Resolve the thread after you post that reply and push the fix. +1. When you fixed it in another PR, the Problem, or a follow-up issue, say which + one and give its number. +1. Reply and leave the thread open when you disagree. The reviewer decides, per + [DEV-410](./DEV-410.md). ```md -Good: fixed in 4a1c2f0, the heading is now `###`. [Resolve] Bad: [Resolve] +Good: fixed in 4a1c2f0, the heading is now `###`. [Resolve] +Bad: [Resolve] ``` ### Acceptance Criteria -- [ ] Every inline thread on the PR is resolved or explicitly left open at merge -- [ ] Each resolved thread carries a reply naming what changed -- [ ] A fix made outside this PR names where it landed, by number -- [ ] No thread is resolved without a reply +- [ ] Every inline thread on the PR has a reply at merge +- [ ] Each reply names what changed, or the PR or issue that carries the fix +- [ ] Every thread still open at merge holds a stated disagreement diff --git a/docs/rules/README.md b/docs/rules/README.md index b9df4e0..dd28c94 100644 --- a/docs/rules/README.md +++ b/docs/rules/README.md @@ -91,7 +91,7 @@ How to review, and the quality bar work is held to. - [DEV-420](./DEV-420.md): scout open PRs when idle - [DEV-430](./DEV-430.md): deliver bug-free work; review is a safety check - [DEV-440](./DEV-440.md): judge work by value delivered, not effort spent -- [DEV-450](./DEV-450.md): resolve every inline thread before merging +- [DEV-450](./DEV-450.md): resolve every inline thread with its answer ### 5. Advocacy