A review is an object
In most tools, a review is a pile of comments attached to a diff. In Branchwork it is a thing in its own right, with a reviewer, a verdict, a set of notes, and the exact range of revisions it covered.
That last part is what makes everything else possible.
Leaving a review
- Open a change.
- Hover a line in the diff. A blue plus appears in the gutter.
- Click it, write your note, click Add to review.
- The note sits in yellow as pending. Nobody can see it yet.
- Repeat for as many lines as you like.
- Choose a verdict at the bottom and click Submit review.
Notes are held until you submit deliberately. Half a review arriving in someone's inbox one note at a time is noise, and it pressures the author to start fixing before you have finished thinking.
The three verdicts
- Comment - notes without judgement. Questions, suggestions, things worth saying that do not block anything.
- Approve - you are happy for this to land as it stands. You cannot approve your own change; the option is not shown to the author.
- Request changes - this should not land until the notes are addressed.
Since your last review
The feature everyone wants. When you open a change you have reviewed before, Branchwork opens on the diff between the revision you last signed off on and the current head.
If you reviewed r2 and the author has pushed r3 and r4, you see what changed across r3 and r4. Not the whole change. Not a mental exercise in remembering which parts you already read. Full change is one click away whenever you want it.
This works because a review records its range. It is a lookup and a diff, not a heuristic, so it is exactly right every time.
Stale reviews
When new revisions land after a review, that review is marked stale. It is not deleted and not hidden. What somebody approved is a fact worth keeping, and the honest statement is "Sam approved r1 through r2", not "Sam approved" next to code Sam never saw.
A review that still covers the current head is marked current.
Notes and resolving
A note belongs to a file, a line, and a side of the diff - the old file or the new one. A note on line 10 of the new file and a note on line 10 of the old file are different places, and Branchwork keeps them apart.
Notes are resolved separately from reviews, by either the person who wrote the note or the author of the change. A note outlives the review it arrived in: the author can close it after fixing the code, without anyone having to re-review to make it go away.
Open note counts appear next to every change in the stack rail, so it is obvious where the unfinished conversations are.
A known limitation
Notes anchor to a fixed line number. If a later push inserts lines above a note, that note can end up pointing a few lines off. We would rather write that down than pretend. Fixing it properly means remapping every note through the diff on each push, and it is on the list.
Reviewing from the terminal
bw review list shows what is waiting on you: open changes you did not write, where your last review is older than the current head. bw review show <id> prints the same incremental diff the website opens on.
You cannot submit a verdict from the terminal. Approving code is worth doing in a place where you can see it properly, at least until the terminal view has earned more trust. See the CLI docs.
How to review well here
- Review the bottom of the stack first. Changes above it assume it is correct, so a problem at the bottom invalidates the review above it.
- Use Comment more than you think. Request changes is for things that should genuinely block.
- Say why, not just what. "This breaks on empty input" is a review; "fix this" is a chore.
- If you find yourself writing a long note about structure, that is usually a conversation, not a note.