home-assistant-controller/REVIEW.md

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.