43 lines
2.0 KiB
Markdown
43 lines
2.0 KiB
Markdown
# Code Review Guidelines
|
|
|
|
|
|
- Each MR should be focused, changing only one concept at a time
|
|
- Keep MRs small - aim for under 500 lines of diff. There can be some wiggle room for cases that are hard to split
|
|
- When reviewing code, check for test coverage and suggest tests if missing
|
|
- Go through tests and think hard to see if any unit tests or group of unit tests can be replaced with a property test
|
|
- When suggesting a property test, consider cases that the property needs to falsify and whether it needs its own generator
|
|
- Business logic stays pure
|
|
|
|
## Comments
|
|
|
|
- Less is more
|
|
- If there's comments for a function, verify they're proper haddock style
|
|
- If there's comments for a function, they must only be about the contract and use instructions
|
|
- If there's comments for implementation, they should only be for exceptional cases, cases where the reader would question why something is implemented like that
|
|
- Comment style should follow minimalistic writing style
|
|
|
|
## Recording reviews
|
|
|
|
Reviews are stored as git notes under `refs/notes/review`, one note per
|
|
reviewed commit. The note header carries `branch`, `round`, `verdict`
|
|
(`approve` or `request-changes`), `previous` (sha of the last reviewed tip),
|
|
and a findings list with stable IDs (`F1`, `F2`, ...) whose `status` is
|
|
`open`, `resolved`, or `wontfix`. The body is free markdown prose.
|
|
|
|
Protocol:
|
|
|
|
1. Fetch prior results:
|
|
`git fetch origin "refs/notes/review:refs/notes/review"`
|
|
2. Read the latest verdict and open findings for the branch:
|
|
`scripts/review-note latest <branch>`
|
|
3. Review the branch tip per this document.
|
|
4. Write the note (header + markdown) to a file and attach it to the tip:
|
|
`scripts/review-note write <file>`. Use `--force` only to replace a note
|
|
on the same commit deliberately.
|
|
5. Publish: `scripts/review-note push` (plain `git push` does not push
|
|
notes).
|
|
|
|
On a re-review after fixes: new tip, new note, `round`+1, `previous` set to
|
|
the last reviewed sha, open findings carried forward by ID, resolved ones
|
|
marked `resolved`.
|