From 773f3b550ffeb2175e2909251c491b4781ccc308 Mon Sep 17 00:00:00 2001 From: Mats Rauhala Date: Fri, 2 Oct 2026 14:47:46 +0300 Subject: [PATCH] Review notes docs --- AGENTS.md | 3 ++- REVIEW.md | 25 +++++++++++++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 75b93bc..b8962ee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,4 +33,5 @@ reactive programming (AFRP). Haskell, built with cabal. ## Reviewing -See [[REVIEW.md]] +Reviews are recorded in git notes under `refs/notes/review`; read the latest +note before reviewing. See [[REVIEW.md]]. diff --git a/REVIEW.md b/REVIEW.md index 4dcd7e2..4876c6b 100644 --- a/REVIEW.md +++ b/REVIEW.md @@ -15,3 +15,28 @@ - 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 ` +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 `. 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`.