The Unwritten Rules of Review Etiquette: Stories from Maintainers Who Built Trust in Open Source

Open source code review is often described as a technical gatekeeping process—a final check before merging. But ask any long-time maintainer, and they'll tell you it's really a human process. The difference between a thriving community and a toxic one often comes down to how review conversations are handled. We've collected stories from maintainers across several mid-sized projects, anonymized to protect the candid, to illustrate what works and what doesn't. This guide is for anyone who reviews code, whether you're a first-time contributor or a project lead. By the end, you'll have a mental model for review etiquette that goes beyond 'be nice'—you'll understand the mechanics of building trust through feedback.

Why Review Etiquette Matters More Than You Think

When a project ignores review etiquette, the first thing to suffer is contributor retention. One maintainer of a popular JavaScript library recounted how a single harsh comment caused a first-time contributor to delete their pull request and never return. That contributor had spent a weekend on the patch. The comment wasn't malicious—it was just blunt: 'This is wrong, rewrite it.' No explanation, no appreciation for the effort. The maintainer later realized that the code was actually correct, just unconventional. The damage was done.

Poor review etiquette doesn't just scare away newcomers. It also creates an environment where even experienced contributors become defensive. When feedback feels like a personal attack, people stop listening. They argue, they ignore suggestions, or they disengage entirely. The project suffers because good ideas get lost in conflict, and the review queue slows down as everyone tiptoes around egos.

On the flip side, maintainers who invest in review etiquette see compounding returns. One maintainer of a data visualization library described how their project's review culture became a selling point: 'Contributors tell us they stay because they feel respected. They know their code will be critiqued fairly, and they'll learn something.' This project now has a 40% repeat-contributor rate, well above the open source average. Trust built in reviews translates directly to community growth and code quality.

The Cost of Bad Reviews

A single bad review can cost a project weeks of community goodwill. Consider the hidden costs: time spent soothing hurt feelings, threads derailed by meta-discussions, and the loss of future contributions from someone who felt dismissed. One maintainer of a Python web framework estimated that 30% of their review time was spent on 'emotional cleanup'—apologizing, clarifying intent, or mediating disputes. That's time not spent on actual code improvement.

The Ripple Effect of Good Reviews

Good reviews create a positive feedback loop. Contributors who feel heard are more likely to review others' code, spreading the etiquette norms. They also become more resilient to criticism, because they trust the reviewer's intent. One maintainer shared a story of a contributor who initially submitted a messy pull request, received patient, constructive feedback, and eventually became one of the project's most thorough reviewers. That transformation started with a review that said, 'This is a great start. Let's work on the error handling together.'

What to Settle Before the First Review

Before you dive into reviewing code, there are a few things you need in place to set yourself and the contributor up for success. The maintainers we spoke to all emphasized that the best reviews happen when expectations are clear from the start.

Set Contribution Guidelines Early

A project without clear contribution guidelines is like a restaurant without a menu—people will order whatever they want, and you'll have to send it back. At minimum, your CONTRIBUTING.md should cover: coding style preferences (and whether you enforce a linter), how to write commit messages, what a good pull request description looks like, and the review process timeline. One maintainer of a Rust crate said their guidelines reduced 'wrong' pull requests by 60% because contributors knew not to submit changes without an issue discussion first.

Define Review Roles and Responsibilities

Who reviews what? How many approvals are needed? Is there a distinction between 'reviewer' and 'maintainer'? Small projects often wing this, but as the community grows, ambiguity breeds inconsistency. Some projects use a rotating reviewer schedule to prevent burnout. Others assign reviewers based on area of expertise. The key is to document it so that everyone—including contributors—knows what to expect. One maintainer of a Kubernetes-related tool shared that they created a 'reviewer ladder' that clearly showed the path from occasional contributor to core reviewer. This transparency motivated people to improve their review skills.

Agree on a Communication Tone

This is the squishiest but most important prerequisite. Some projects adopt a formal, impersonal tone (e.g., 'The function does not handle the null case'). Others prefer a friendly, conversational tone (e.g., 'Hey, I think we might need to handle null here—what do you think?'). Neither is inherently right, but inconsistency confuses contributors. One maintainer told us they had a contributor who felt attacked by a reviewer's direct style, while another contributor in the same thread felt the directness was efficient. The solution was to add a note in the contributing guide: 'Our reviewers aim for clarity over politeness. Please don't interpret brevity as hostility.' That simple clarification reduced misunderstandings.

The Core Workflow: How to Review with Trust

Once the groundwork is laid, the actual review process can follow a repeatable pattern. The maintainers we spoke to converged on a sequence of steps that balances thoroughness with respect.

Step 1: Read the Pull Request Description First

It sounds obvious, but many reviewers jump straight to the diff. The description tells you the intent, the context, and any design decisions. If the description is missing or vague, ask for clarification before reviewing. One maintainer said they always start by summarizing the pull request in their own words to confirm understanding: 'So you're adding a new endpoint that returns user stats, and you chose to cache the result for 5 minutes—correct?' This simple habit catches misunderstandings early and shows the contributor you're engaged.

Step 2: Scan for High-Level Issues First

Before nitpicking variable names, look at the overall approach. Does it fit the project's architecture? Are there security implications? Is the change too big? One maintainer of a Django app recalled a pull request that introduced a new database query in a hot loop. The code was clean, but the approach was wrong. They commented on the design before anything else, saving the contributor from fixing line-level issues that would be rewritten anyway. The contributor appreciated the big-picture feedback and later said it taught them to think about performance earlier.

Step 3: Separate Must-Fix from Nice-to-Have

Not all feedback is equal. Use labels like 'blocking', 'suggestion', and 'question' to help the contributor prioritize. One maintainer uses emoji prefixes: 🚫 for bugs, 💡 for improvements, ❓ for questions. This visual cue helps contributors triage quickly. They also make sure to include at least one positive comment ('I like how you handled this edge case') to balance the criticism. This isn't about being soft—it's about reinforcing good patterns.

Step 4: Write Explanatory Comments, Not Commands

Instead of 'Change this to X', explain why: 'Using X here would make it consistent with the rest of the module, and it also handles the timeout case we discussed in issue #42.' When you explain the reasoning, you teach the contributor, and they'll make better decisions next time. One maintainer of a testing framework said that after they started writing explanatory comments, the number of follow-up questions dropped by half. Contributors felt empowered to make judgment calls on their own.

Step 5: Follow Up and Close the Loop

After the contributor addresses your feedback, do a final review promptly. Nothing kills momentum like a week-long wait for approval. If the changes are minor, consider approving with a note that you trust the contributor to merge. One maintainer shared a story where they approved a pull request with a single remaining nitpick, saying 'I'll leave this to your judgment—feel free to merge.' The contributor was thrilled and became a regular. Trust begets trust.

Tools and Setup That Support Good Etiquette

Good intentions aren't enough—you need tools that reinforce respectful, efficient reviews. The maintainers we interviewed recommended a few practical setups.

Use a Checklist Template in Your Review Tool

GitHub and GitLab allow you to save review templates. Create one that reminds you to check for: clear description, test coverage, documentation updates, and security concerns. One maintainer shared their template: 'Before approving, verify: (1) Does the PR description explain the 'why'? (2) Are there tests for new logic? (3) Is there any sensitive data exposure? (4) Does it follow our style guide?' This prevents reviewers from forgetting important checks, especially when reviewing late at night.

Automate the Obvious

Let machines handle style, formatting, and simple linting. Use tools like ESLint, Prettier, or Black to enforce code style automatically. This frees human reviewers to focus on logic, architecture, and design. One maintainer of a Go project said: 'We used to spend 20% of review comments on formatting. After adding a CI check, those comments disappeared, and the tone of reviews improved because we only talked about substance.'

Set Up a 'Review Queue' Dashboard

If your project has multiple reviewers, a dashboard showing open pull requests and their assigned reviewers can prevent duplication and neglect. Some projects use a bot that pings reviewers after 48 hours of inactivity. One maintainer of a large monorepo said their bot reduced stale pull requests from 30 to 5 per week, and contributors appreciated the transparency.

Consider Asynchronous Review Sessions

For complex changes, some teams schedule a 'review party' where multiple reviewers look at the same pull request together in a video call. This can be more efficient than back-and-forth comments, especially for architectural decisions. One maintainer of a machine learning library said they do this monthly for major features, and it has become a learning opportunity for junior contributors who watch the discussion.

Variations for Different Project Sizes and Cultures

Not every project can follow the same review playbook. The maintainers we spoke to adapted their etiquette based on project maturity, contributor base, and community norms.

Small Projects with Few Maintainers

In a two-person project, every review is personal. One maintainer of a small command-line tool said they lean into informality: 'I'll say things like 'this looks good, but I think we can simplify the loop—want to pair on it?' The key is to avoid sounding like a boss. Since you're likely friends or close collaborators, the tone can be more casual, but don't skip the explanation. Even in a small project, explaining why helps the other person learn.

Growing Projects with a Mix of Newcomers

This is the hardest stage. You have experienced contributors who know the codebase and newcomers who don't. The etiquette needs to accommodate both. One maintainer of a web framework said they created two review tracks: 'fast-track' for small, low-risk changes from trusted contributors (approval by one reviewer), and 'standard' for everything else. They also assign a 'mentor reviewer' to first-time contributors, who does a thorough but patient review. This prevents newcomers from being overwhelmed by multiple reviewers while still maintaining quality.

Large Projects with Formal Governance

In projects with dozens of maintainers, written policies become essential. One maintainer of a cloud-native project shared their 'Code Review Policy' document, which specifies: minimum two approvals for any change, a 24-hour waiting period for non-trivial changes, and a requirement that reviewers explain their 'request changes' votes. They also have a 'code review bot' that enforces these rules automatically. While this sounds bureaucratic, the maintainer said it reduced disputes because everyone knew the rules upfront.

Cross-Cultural and Remote Teams

When contributors span time zones and cultures, misunderstandings multiply. One maintainer of an international project said they adopted a 'no sarcasm' rule in reviews because humor doesn't translate well. They also encourage reviewers to avoid absolute language like 'always' or 'never'. Instead of 'You should never use global variables', they say 'In our codebase, we prefer to avoid globals because they make testing harder—here's how we handle state instead.' This nuance prevents defensiveness and teaches the rationale.

Pitfalls, Debugging, and What to Check When Reviews Go Wrong

Even with the best intentions, reviews can go sour. The maintainers we spoke to identified several common failure modes and what they did to fix them.

The 'Drive-By' Comment Problem

A drive-by comment is a nitpick from someone who hasn't read the full context. For example, a reviewer might say 'Use const instead of let' on a line that's part of a larger refactor, without realizing the variable is reassigned later. These comments waste everyone's time. One maintainer's solution: require reviewers to state they've read the entire pull request before leaving feedback. They added a checkbox in their review template: 'I have read the full diff and understand the context.' This simple step reduced irrelevant comments by 70%.

Review Fatigue and Burnout

When the same people review everything, they get tired, and their comments become shorter, more negative, or more dismissive. One maintainer of a database library said they implemented a 'review cap' of three pull requests per day per reviewer. If you hit the cap, you're encouraged to take a break or focus on other tasks. This prevented burnout and kept review quality high. They also rotated reviewers every quarter to spread the load.

Defensive Contributors and Escalation

Sometimes a contributor pushes back hard on feedback. The maintainers advised not to escalate. Instead, ask clarifying questions: 'Can you help me understand why you chose this approach?' This shifts the conversation from conflict to collaboration. If the contributor remains hostile, a maintainer should step in privately. One maintainer shared a story where a contributor was repeatedly dismissive in comments. The maintainer sent a direct message saying, 'I value your contributions, but the tone in reviews is making others uncomfortable. Can we find a way to disagree constructively?' The contributor apologized and improved.

When to Override a Review Decision

Sometimes a reviewer blocks a change for subjective reasons. The maintainer should have a clear escalation path. One project uses a 'lazy consensus' rule: if a review has been open for 72 hours with no objections, it can be merged even if some reviewers haven't approved. This prevents one person from blocking progress indefinitely. Another project has a 'final say' maintainer who can override a review after a discussion period. These mechanisms should be documented and used sparingly.

What to Check When Reviews Are Consistently Negative

If a project's review queue is full of 'request changes' and few approvals, the problem might be cultural. Are reviewers setting the bar too high? Are they asking for perfection instead of progress? One maintainer realized their team was rejecting pull requests for missing edge cases that were unlikely to occur. They adjusted the standard to 'good enough for production, with room for improvement tracked in issues.' This doubled the merge rate and contributor satisfaction.

Finally, remember that review etiquette is a practice, not a policy. It evolves as your community grows. The maintainers who built trust didn't get it right overnight—they iterated, listened to feedback, and adjusted. The unwritten rules become written over time, but the spirit of respect and learning must remain. Start with one change today: the next time you review, add a positive comment before any criticism. See how it feels. Your contributors will notice.