Skip to content

Pull requests reviews and replies

Lucian Lungu edited this page Nov 10, 2026 · 2 revisions

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.

Why

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.

Ground rules

  • 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.

The PR title and description

  • Title: a conventional commit, type(scope): what changes, lowercase, under about 70 characters. fix(smb): refuse TREE_CONNECT when the share permission cannot be resolved rather than SMB 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.

Review comments

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 suggestion block 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 itself

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:

  1. Summary: the first sentence names what blocks the merge, or says nothing does.
  2. Critical issues: what blocks it (correctness, security, breaking changes).
  3. Suggestions: performance or maintainability.
  4. Questions: what you need to know before you can judge.
  5. 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.

What to look at

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.

Replying to a review

  • 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.

Clone this wiki locally