Code Review Guidelines

Every PR to a UAI repository goes through review before merge. Review keeps our code correct, readable, maintainable, and secure, and it helps everyone on the team share context. It works best when we treat it as a collaboration rather than a gate.

Before you raise a PR

Keep each PR small and focused on one thing. Small PRs are quicker to review, invite better feedback, and are easier to revert. If a change is growing large, split it into a stack of smaller PRs where you can.

It is completely fine to raise a large PR early as a Draft to get feedback on the approach before investing in the details. Just say in the description what you would like feedback on.

Review your own PR first, reading the full diff as a reviewer would:

• Remove debug code, commented-out blocks, and unrelated changes.
• Confirm tests pass and cover the change.
• Add inline notes where you made a trade-off or a decision that is not obvious.
• Write a description that explains what changed, why, and how to validate it.

Please request review only once CI is green. If something is failing for a known reason, a quick note in the description saves the reviewer time.

Assigning reviewers

Assign one reviewer per PR. A single clear owner keeps responsibility clear and avoids conflicting feedback.

If a PR is complex and either the author or the reviewer feels a second opinion would help, the first reviewer finishes their review, then invites a second reviewer. We do not block on two reviewers by default.

Review SLO

Try to review within 48 hours of being assigned.

If you do not have the bandwidth, please do not sit on the PR or stretch yourself thin. Hand it off to another reviewer as soon as you can so the author is not left waiting. Unblocking a teammate quickly matters more than holding on to the review.

Comments: writing and receiving them

Assume good intent on both sides. Review is about the code, never the person. Try not to take comments personally, and take the same care not to make them personal. A little warmth goes a long way.

Aim for comments that stand on their own:

• Include enough context, and where it helps a concrete suggestion or example, so the author can act without a round of back-and-forth.
• Explain the why, not just the what.
• Mark optional suggestions clearly as non-blocking, so it is easy to tell what needs to change before merge.
• If a piece of code is unclear to you, it is genuinely helpful to say so and ask. Questions are welcome, not a sign of anything lacking.

Please batch your feedback using Start a review rather than posting comments one at a time. Each individual comment sends its own email or GitHub notification, whereas a review is submitted as a single notification. The same applies when responding to comments. A quick emoji, such as a green check mark, is a friendly way to show a comment has been acknowledged.

Once you have been through the diff, a short summary such as “Looks good, a couple of small things” or “Approving, nothing blocking” lets the author know where they stand.

As the author, try to respond to every comment, resolve only the threads you have fully addressed, and re-request review when you are ready for another round.

When a review starts to drag

Async review is our default and works well for most changes. If a PR is going through many cycles or a thread is not converging, it is often faster and kinder to switch to sync. Ping the reviewer or author, hop on a quick call, or pair on it together. Once you have sorted things out, paste a short summary of the discussion back into the PR so the context is not lost.

Merging

• At least one approval before merge.
• No one approves their own PR.
• Resolve or explain any failing checks before merging.
• Squash when the commit history is messy, so main stays clean.

Finding the balance

Be thorough enough to catch real bugs and design problems, while telling apart doing things right from doing things right now. It is kinder to everyone not to ask for a large refactor in an urgent fix. Lean on linters and formatters for style rather than review comments. Doing things well today usually beats doing them perfectly tomorrow.