Method
- standard
- A stranger can reproduce the change from the pull request alone, and disprove it. Otherwise it is not finished.
What a change ships with
| part | meaning |
|---|---|
| Problem | What breaks, in one checkable sentence. |
| Environment | Commit, versions, operating system, the exact commands. |
| Failing test | The command that is red before the change. |
| Solution | The minimal diff. |
| Proof | Output before and after, plus the rest of the suite. |
Rules
01 Reproduce before diagnosing, diagnose before changing
- A command or a test that shows the fault comes first.
- Nothing is changed without a reproduced fault, not even when the cause looks obvious.
02 The failing test goes in first
- It belongs in the pull request, red before the fix and green after.
- Both runs are actually executed and both outputs go into the description.
03 No regression, and no silence about one
- The rest of the suite ran before and runs after.
- If it was already red, that is stated rather than left out.
04 Minimal diff
- Only what solves the problem. No reformatting, no drive-by cleanup, no style alignment.
- Everything else becomes its own pull request.
05 Evidence, not assertion
- What an issue thread says is a claim. Every claim taken from it is checked against the actual code.
- Wrong advice in the thread is refuted explicitly, with the reasoning.
06 The reasoning is part of the delivery
- Why this way and not the more obvious one. What was rejected, and on what grounds.
- That belongs in the commit body and the pull request, not in a chat window.
07 A mock moves the risk, it does not remove it
- Injecting a dependency to make logic testable relocates the untested part into the seam, and the real implementation then needs its own test.
- In one pull request both halves took an injected does-this-exist, every test passed a mock, the mock was right and the real check was wrong. No test could fail. Two review bots found it immediately.
08 A silent failure is an invented zero
- An aborted call and a genuine no-match look identical in any report.
- So: fail loudly, or check the number against an independent second source.
- A checker that examined nothing reports zero problems exactly like one that examined everything.