From 5e005a64c194abf30c12ea47fd057f8d8f7e0edf Mon Sep 17 00:00:00 2001 From: Vadim Zolotokrylin <1125014+zolotokrylin@users.noreply.github.com> Date: Tue, 14 Jul 2026 22:57:24 +0800 Subject: [PATCH 1/3] docs(rules): run the review process as rules --- docs/CONTRIBUTING.md | 39 ++++++++------------------------------- docs/rules/DEV-410.md | 32 ++++++++++++++++++++++++++++++++ docs/rules/DEV-420.md | 24 ++++++++++++++++++++++++ docs/rules/DEV-430.md | 30 ++++++++++++++++++++++++++++++ docs/rules/README.md | 9 +++++++-- 5 files changed, 101 insertions(+), 33 deletions(-) create mode 100644 docs/rules/DEV-410.md create mode 100644 docs/rules/DEV-420.md create mode 100644 docs/rules/DEV-430.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index d50c66e..68e46ca 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -7,11 +7,10 @@ approachable and respectful. > You can use [Wizard GitHub App][2] and [Wizard Browser Extension][1] to > simplify some of the workflows described in these Guidelines. -These conventions are being restructured into a -[rules system](./rules/README.md): small numbered files that each enforce one -checkable behavior. The Authoring rules (`DEV-0xx`) define how a rule is -written; the remaining categories migrate the sections below into rules. This -document threads them with the workflow narrative. +The enforceable conventions live in a [rules system](./rules/README.md): small +numbered `DEV-` files that each enforce one checkable behavior. This document is +the narrative guide over them, threading the rules with the workflow context. +When a rule and this guide ever disagree, the rule is the source of truth. ## Table of Contents @@ -112,32 +111,10 @@ rule that defines it: ### Review Process -#### Giving a Review - -If a PR is not ready to merge, you **must** use **Request Changes** (reject). Do -not leave a plain comment when rejection is warranted — comments do not block -merging, are not recorded as rejections, and prevent the author from -re-requesting a review. - -Use **Request Changes** (reject) for objective problems: - -- PR doesn't solve the stated problem. -- A bug is introduced. -- Code style is inconsistent. -- Required guidelines are violated. - -Use **Comment** for optional improvements or suggestions that should not block -the PR. - -#### Scout Approach - -When not actively working on a PR, look for PRs that need reviewers and offer -timely feedback to keep work moving. - -#### Code Quality - -Deliver bug-free software. Push back on subjective feedback — reviewers are a -final safety check, not a QA team. +- [DEV-410](./rules/DEV-410.md): reject with Request Changes for objective + problems +- [DEV-420](./rules/DEV-420.md): scout open PRs when idle +- [DEV-430](./rules/DEV-430.md): deliver bug-free work; review is a safety check --- diff --git a/docs/rules/DEV-410.md b/docs/rules/DEV-410.md new file mode 100644 index 0000000..d32015b --- /dev/null +++ b/docs/rules/DEV-410.md @@ -0,0 +1,32 @@ +--- +id: DEV-410 +title: "Reject With Request Changes for Objective Problems" +status: "active" +enforcement: "manual" +severity: "error" +depends_on: ["DEV-360"] +--- + +## Reject With Request Changes for Objective Problems + +### Problem + +Leaving a plain comment on a PR that should be rejected does not block the +merge, is not recorded as a rejection, and stops the author from re-requesting +review. Real problems slip through as if they were optional. + +### Solution + +Match the review action to the finding. + +1. When a PR is not ready to merge, use **Request Changes** for objective + problems: it does not solve the stated problem, it introduces a bug, its code + style is inconsistent, or it violates a required guideline. +1. Use **Comment** for optional improvements or suggestions that should not + block the PR. + +#### Acceptance Criteria + +- [ ] Objective problems get Request Changes, not a plain comment +- [ ] Optional suggestions use Comment +- [ ] A rejection names the objective problem it is based on diff --git a/docs/rules/DEV-420.md b/docs/rules/DEV-420.md new file mode 100644 index 0000000..c441f64 --- /dev/null +++ b/docs/rules/DEV-420.md @@ -0,0 +1,24 @@ +--- +id: DEV-420 +title: "Scout Open PRs When Idle" +status: "active" +enforcement: "manual" +severity: "warning" +--- + +## Scout Open PRs When Idle + +### Problem + +PRs wait and stall when no one picks them up for review. Work that is otherwise +ready sits idle because reviewers are focused only on their own changes. + +### Solution + +When you are not actively working on a PR of your own, look for PRs that need +reviewers and offer timely feedback to keep work moving. + +#### Acceptance Criteria + +- [ ] Idle time is spent reviewing PRs that are waiting for a reviewer +- [ ] Feedback is given promptly enough to keep the work moving diff --git a/docs/rules/DEV-430.md b/docs/rules/DEV-430.md new file mode 100644 index 0000000..3aa4459 --- /dev/null +++ b/docs/rules/DEV-430.md @@ -0,0 +1,30 @@ +--- +id: DEV-430 +title: "Deliver Bug-Free Work; Review Is a Safety Check" +status: "active" +enforcement: "manual" +severity: "error" +depends_on: ["DEV-410"] +--- + +## Deliver Bug-Free Work; Review Is a Safety Check + +### Problem + +Treating reviewers as the QA team pushes defects downstream, slows everyone, and +lets subjective debates block otherwise sound work. + +### Solution + +Own the quality of what you deliver. + +1. Deliver bug-free software. Do not rely on review to catch defects you could + have caught yourself. +1. Treat reviewers as a final safety check, not a QA team. +1. Push back on subjective feedback rather than absorbing it as a blocker. + +#### Acceptance Criteria + +- [ ] Work is delivered bug-free, not dependent on review to find defects +- [ ] Review is treated as a final safety check, not QA +- [ ] Subjective feedback is pushed back on rather than blocking the PR diff --git a/docs/rules/README.md b/docs/rules/README.md index a72ef17..43a6edf 100644 --- a/docs/rules/README.md +++ b/docs/rules/README.md @@ -54,8 +54,13 @@ What a pull request must satisfy before it merges. - [DEV-360](./DEV-360.md): follow the PR lifecycle - [DEV-370](./DEV-370.md): report time across all stages -The remaining categories are migrating from the -[Contributing Guidelines](../CONTRIBUTING.md) into rules. +### 4. Review + +How to review, and the quality bar work is held to. + +- [DEV-410](./DEV-410.md): reject with Request Changes for objective problems +- [DEV-420](./DEV-420.md): scout open PRs when idle +- [DEV-430](./DEV-430.md): deliver bug-free work; review is a safety check ## Rule file format From 117ca24e200c4f27a21f4631aa49969abc627d88 Mon Sep 17 00:00:00 2001 From: Vadim Zolotokrylin <1125014+zolotokrylin@users.noreply.github.com> Date: Tue, 14 Jul 2026 23:05:18 +0800 Subject: [PATCH 2/3] docs(rules): drop the repeated title heading from rules --- docs/rules/DEV-410.md | 8 +++----- docs/rules/DEV-420.md | 8 +++----- docs/rules/DEV-430.md | 8 +++----- 3 files changed, 9 insertions(+), 15 deletions(-) diff --git a/docs/rules/DEV-410.md b/docs/rules/DEV-410.md index d32015b..e9447b3 100644 --- a/docs/rules/DEV-410.md +++ b/docs/rules/DEV-410.md @@ -7,15 +7,13 @@ severity: "error" depends_on: ["DEV-360"] --- -## Reject With Request Changes for Objective Problems - -### Problem +## Problem Leaving a plain comment on a PR that should be rejected does not block the merge, is not recorded as a rejection, and stops the author from re-requesting review. Real problems slip through as if they were optional. -### Solution +## Solution Match the review action to the finding. @@ -25,7 +23,7 @@ Match the review action to the finding. 1. Use **Comment** for optional improvements or suggestions that should not block the PR. -#### Acceptance Criteria +### Acceptance Criteria - [ ] Objective problems get Request Changes, not a plain comment - [ ] Optional suggestions use Comment diff --git a/docs/rules/DEV-420.md b/docs/rules/DEV-420.md index c441f64..99fa364 100644 --- a/docs/rules/DEV-420.md +++ b/docs/rules/DEV-420.md @@ -6,19 +6,17 @@ enforcement: "manual" severity: "warning" --- -## Scout Open PRs When Idle - -### Problem +## Problem PRs wait and stall when no one picks them up for review. Work that is otherwise ready sits idle because reviewers are focused only on their own changes. -### Solution +## Solution When you are not actively working on a PR of your own, look for PRs that need reviewers and offer timely feedback to keep work moving. -#### Acceptance Criteria +### Acceptance Criteria - [ ] Idle time is spent reviewing PRs that are waiting for a reviewer - [ ] Feedback is given promptly enough to keep the work moving diff --git a/docs/rules/DEV-430.md b/docs/rules/DEV-430.md index 3aa4459..51cf523 100644 --- a/docs/rules/DEV-430.md +++ b/docs/rules/DEV-430.md @@ -7,14 +7,12 @@ severity: "error" depends_on: ["DEV-410"] --- -## Deliver Bug-Free Work; Review Is a Safety Check - -### Problem +## Problem Treating reviewers as the QA team pushes defects downstream, slows everyone, and lets subjective debates block otherwise sound work. -### Solution +## Solution Own the quality of what you deliver. @@ -23,7 +21,7 @@ Own the quality of what you deliver. 1. Treat reviewers as a final safety check, not a QA team. 1. Push back on subjective feedback rather than absorbing it as a blocker. -#### Acceptance Criteria +### Acceptance Criteria - [ ] Work is delivered bug-free, not dependent on review to find defects - [ ] Review is treated as a final safety check, not QA From e6aca1718d077a404d92b0552d75fb86f3a02ae3 Mon Sep 17 00:00:00 2001 From: Vadim Zolotokrylin <1125014+zolotokrylin@users.noreply.github.com> Date: Wed, 15 Jul 2026 10:11:30 +0800 Subject: [PATCH 3/3] docs(rules): rewrite review-rule solutions as method not checks --- docs/rules/DEV-420.md | 9 +++++++-- docs/rules/DEV-430.md | 14 +++++++++----- 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/docs/rules/DEV-420.md b/docs/rules/DEV-420.md index 99fa364..0f1fafc 100644 --- a/docs/rules/DEV-420.md +++ b/docs/rules/DEV-420.md @@ -13,8 +13,13 @@ ready sits idle because reviewers are focused only on their own changes. ## Solution -When you are not actively working on a PR of your own, look for PRs that need -reviewers and offer timely feedback to keep work moving. +Reviewing is shared work, not something that happens only to your own PRs. When +your own work is not blocking you, spend that idle time clearing the queue so +ready changes do not wait on attention. + +Look for PRs that have no reviewer or are still waiting on one, and give +feedback while it still moves the work. A fast review on a ready PR is worth +more than a thorough one a day later. ### Acceptance Criteria diff --git a/docs/rules/DEV-430.md b/docs/rules/DEV-430.md index 51cf523..dfe6a2e 100644 --- a/docs/rules/DEV-430.md +++ b/docs/rules/DEV-430.md @@ -14,12 +14,16 @@ lets subjective debates block otherwise sound work. ## Solution -Own the quality of what you deliver. +Own the quality of what you ship instead of outsourcing it to review. A reviewer +who has to find your bugs becomes a bottleneck, and a defect caught in review +costs more to fix than one you catch before opening the PR. -1. Deliver bug-free software. Do not rely on review to catch defects you could - have caught yourself. -1. Treat reviewers as a final safety check, not a QA team. -1. Push back on subjective feedback rather than absorbing it as a blocker. +Test and self-review the change until you believe it is bug-free, then request +review. Treat the reviewer as a final safety check on work you already trust, +not the QA pass that first exercises it. When feedback is subjective rather than +an objective problem (see [DEV-410](./DEV-410.md)), discuss and push back +instead of absorbing every preference as a required change, so sound work does +not stall on taste. ### Acceptance Criteria