Set clear code review expectations with contributors

Code review is where a contributor learns how your project expects things to be done, and it is also where misunderstandings show up. Contributors wonder whether anyone has seen their pull request, what they need to change, and when it counts as done. Maintainers wonder whether a contributor will follow up. Clear review expectations, agreed before the work starts, answer those questions up front.

Say how long review usually takes

Pick a realistic response time and publish it: "We aim to give a first review within three working days." A slow, predictable reviewer is easier to work with than a fast, unpredictable one. If you are going to be away, say so and say when you'll be back.

Ask the same of contributors. If a reviewer requests changes, how long can the pull request sit before it is closed or handed to someone else? Agreeing on that up front makes closing a stale pull request a normal step, not a judgment.

Define what done means before work starts

Review goes best when both sides compare the work to the same written criteria. Before a contributor starts, the issue should state what behavior changes, what tests are expected, and what documentation must be updated. During review, point back to those criteria. If you discover a new requirement, say so explicitly and decide together whether it belongs in this change or a follow-up.

Separate blocking feedback from suggestions

Not every comment needs to be addressed before merging. Make the difference visible. Many teams prefix comments with labels such as "blocking", "suggestion", or "question". However you mark it, a contributor should be able to tell which comments stand between them and a merge.

• Blocking: the change can't be accepted until this is addressed.
• Suggestion: worth considering, fine to leave for later.
• Question: the reviewer needs to understand something before deciding.
• Praise: something done well that the contributor should keep doing.

Explain the why, not only the what

"Rename this" gets one change. "We name handlers after the event they respond to, so this should be onIssueClosed" teaches a rule the contributor can apply everywhere. For newer contributors especially, a short reason with each request is the difference between fixing one pull request and getting better at the project.

Agree how changes are requested and resubmitted

Decide whether contributors should push new commits or rewrite history, whether they should resolve review threads themselves, and how they should signal that a pull request is ready for another look. Small conventions like these remove a lot of uncertainty from the second and third rounds of review.

Keep some feedback private

Public review threads are part of a project's record. Coaching about working habits, communication, or confidence often belongs somewhere private. Decide where that feedback goes, and keep the public thread focused on the code.

For contributors: what to expect

If you are contributing, ask about these expectations before you start: who reviews, how quickly, what done means, and how to ask for another look. Requested changes are a normal part of the process, not a rejection. Responding to them clearly and promptly is one of the most visible skills you can show in open source.

In a Devprentice program, the reviewer and acceptance criteria are named before anyone joins. Reviewers can request changes, accept work, and leave private feedback with next steps, and a named person, not an AI, decides whether work meets the criteria.