Repository navigation
Pull requests reviews and replies
How we write everything that goes on a DittoFS pull request: the title and description, review comments, the review
itself, and replies. This page summarizes #3196; if they ever differ,
.github/instructions/pr-opening.instructions.md
(the title and description),
.github/instructions/pr-commenting.instructions.md
(comments, reviews and replies) and the PR template win.
Whoever reads your PR or comment is reviewing other PRs the same day. Long walls of text get skimmed, and what matters gets lost in them. Write to save the reader's time, not to look thorough.
- Lead with the point. The first sentence says what matters. No preamble, and no restating the task, the code or the comment you answer.
- Show code instead of describing it. If a fix or an alternative fits in a snippet, post the snippet.
- Short beats complete. Leave out what the diff already shows, what a linter or CI would catch, and anything you are not sure of.
- Say how you know. "Ran it", "read the code" or "I think". Never invent behavior, numbers or references.
- A person owns what is posted. Whoever posts has read every line and can defend it. Drafts from an AI agent stay drafts until a person has read them; a bot that posts on its own, such as Copilot code review, is the exception. Keep it short enough to read in under a minute.
-
Title: a conventional commit,
type(scope): what changes, lowercase, under about 70 characters.fix(smb): refuse TREE_CONNECT when the share permission cannot be resolvedrather thanSMB improvements. - One screen. The description fits without scrolling. Delete any section that would be empty or obvious. If the PR can't be explained in one screen it is probably too big: say so, and suggest how to split it.
- The template's sections:
- Description: one to three sentences on what changes in behavior and why. Link the issue or RFC instead of re-explaining it.
- Decision needed: one line on what you need from the reviewer: "approve as is", "pick A or B", "check the locking in X".
- Changes made: what a reviewer needs to know, not every file. Where to start, which files are mechanical (renames, moves, generated code), and which part needs careful eyes.
- Testing: what you ran. Name new tests by the behavior they protect; no pasted logs.
- Additional notes: risks, known limits, follow-ups, what was left out on purpose.
Post them as one review, not one at a time: the author gets one notification instead of one per comment.
How many threads:
- One thread per real objection: a bug, a design concern, a question. Each can then be discussed and resolved on its own. A design point that touches four separate things is four threads.
- One thread for the small stuff. Past three or four nits or small suggestions, list them in a single comment so they don't bury the threads that matter.
Where to anchor:
- On a line, only when the point is about that line. Line comments go outdated and get hidden when the line changes.
- On the file (the comment icon in the file header) for anything broader, such as a design point. File comments survive pushes.
- On the most relevant file for a point about the whole PR, or on the first file if none stands out.
Format: Conventional Comments: a label, the problem in one sentence, why it matters only if that isn't obvious, then the fix as code.
| Label | Meaning |
|---|---|
issue (blocking) |
must change before merge: a bug, data loss, security, a broken contract |
suggestion (non-blocking) |
would improve it; the author decides |
nitpick (non-blocking) |
style or naming; never blocks |
question |
you need information, not a change; ask rather than guess the intent |
praise |
something done well, worth keeping |
More rules:
- Use a GitHub
suggestionblock when the fix fits in the commented lines, so the author applies it in one click. - Link the RFC, spec section or doc behind a point instead of explaining it again.
- Comment once on a repeated problem and say "same in X and Y".
- If a point needs more than a short paragraph, or a thread goes past two rounds, propose a quick live review instead of writing more.
- Every test must be able to fail. A test that would still pass with the change reverted, or that only checks what it just set up, protects nothing and costs CI time. Prefer a compile-time check where one works; otherwise ask for the test to be removed or rewritten.
A good comment looks like this:
issue (blocking): the write error is logged but swallowed, so the caller treats a failed flush as success.
if err := j.write(entry); err != nil { return fmt.Errorf("journal flush: %w", err) }
The review state is the verdict: Request changes if any comment is blocking, Approve if none is, Comment only when you can't judge. Nobody should have to dig the verdict out of the text.
Someone who skips the inline comments must still know whether the PR can merge and what blocks it. Write the body in this order, skipping any part that would be empty:
- Summary: the first sentence names what blocks the merge, or says nothing does.
- Critical issues: what blocks it (correctness, security, breaking changes).
- Suggestions: performance or maintainability.
- Questions: what you need to know before you can judge.
- Praise: what was done well, named precisely enough that nobody undoes it by mistake.
Order points by importance (correctness, then performance, then style) and give each one line that names its thread. The detail lives in the inline comment; don't repeat it in the body.
A guide for reviewing, not a checklist to paste into the review. Report only what fails, as inline comments.
- Protocol: encoding and decoding follow the specs, error codes map correctly, authentication and authorization are right, behavior matches reference implementations.
- Architecture: protocol and business logic stay apart, store interfaces are used as meant, the two-phase write pattern is followed where it applies.
- Code quality: no data races or deadlocks, context cancellation respected, errors handled and structured, thread safety.
- Performance: no needless allocations in hot paths, buffer pools used where they help, efficient algorithms for common operations.
- Security: input validated, permission checks in the right layer, nothing sensitive logged.
- Testing: new code has unit tests, protocol changes have integration or end-to-end tests, error paths are tested.
- Documentation: public APIs commented, user docs and configuration examples updated.
- Applied the change:
Done in <short sha>.and nothing else. - To add to or fix something you already posted, edit that comment instead of posting a new one: one notification instead of two.
- Didn't apply it: one or two sentences on why, with a link if it helps. Still disagreeing after one round? Suggest talking live.
- A top-level comment in the Conversation tab can't be threaded. Answer it in one thread: a file comment on the most relevant file that links the comment and answers its points one by one.