Method
- standard
- If a stranger can't rebuild the change from the pull request alone, and try to prove it wrong, I'm not done.
What a change ships with
| part | meaning |
|---|---|
| Problem | What breaks, in one sentence you can check. |
| Environment | Commit, versions, operating system, the exact commands. |
| Failing test | The command that is red before the change. |
| Solution | The smallest diff that fixes it. |
| Proof | Output before and after, plus the rest of the suite. |
Rules
01 Reproduce before diagnosing, diagnose before changing
- First I need a command or a test that shows the fault.
- Without that I don't change anything, even when the cause looks obvious. Obvious causes are wrong often enough.
02 The failing test goes in first
- It goes into the pull request, red before the fix and green after.
- I run both and paste both outputs into the description. Saying it passed is not the same as showing it.
03 No regression, and no silence about one
- The rest of the suite ran before my change and runs after it.
- If it was already red, I say so instead of leaving it out.
04 Minimal diff
- Only what solves the problem. No reformatting, no cleanup on the side, no style changes.
- Anything else I notice gets its own pull request.
05 Evidence, not assertion
- What an issue thread says is a claim. I check every claim I take from it against the actual code.
- If the thread gives wrong advice, I say why it's wrong. That's often the most useful part of the pull request.
06 The reasoning is part of the delivery
- Why this way and not the more obvious one. What I tried and dropped, and why.
- That goes into the commit body and the pull request, where the next person will find it.
07 A mock moves the risk, it does not remove it
- If I inject a dependency to make logic testable, the untested part moves into the seam. The real implementation then needs its own test.
- I learned that the hard way. In one of my pull requests both halves took an injected does-this-exist, and every test passed a mock. The mock was right and the real check was wrong, so no test could fail. Two review bots found it right away.
08 A silent failure is an invented zero
- An aborted call and a genuine no-match look the same in any report.
- So my tools either fail loudly or check the number against a second, independent source.
- A checker that looked at nothing reports zero problems, just like one that looked at everything.