How to review a pull request
Last updated
Reviewing a pull request means deciding whether one change is safe to merge. It does one thing, its tests and claims hold up, and nobody who depends on it breaks. These are the stable checks for a single change. A reviewer marks each PASS, FAIL, or N/A, and each card links the organisations that publish the practice.
The checks
- chg-one-concern [should-fix]: Make each change do one logical thing; if the description needs "and" between unrelated outcomes, split it.
- chg-size-ceiling [discuss]: Split a change past about 400 changed lines or about 20 files, or say in the description why not; aim for about 200.
- chg-refactor-separate [should-fix]: Put refactors, renames, and reformatting in their own commit or PR, apart from behaviour changes.
- chg-tests-ship-with-change [block]: Ship new or changed behaviour in the same change as a test that fails if the behaviour breaks.
- chg-verify-before-claim [block]: Back every "works" or "bug" claim with something run: a repro, a test or command output.
- chg-breaking-change-taxonomy [block]: Treat any change that callers can observe in a signature, return values, error types, defaults, or side effects as breaking until a consumer check says otherwise.
- chg-author-hygiene [should-fix]: Self-review the diff and write the description before requesting review.
- chg-review-signal [discuss]: Do not spend review comments on what a tool enforces or on minor style points; spend them on the findings that matter.
Run them
To run these checks, paste Read https://goodcodereview.com/llms.txt and use it to review my code. to your agent, or work through them by hand. A diff also takes the function, module, and service cards that its changed lines touch. See the change level for the full list with FAIL and PASS examples.