Open Guide - Dev CoP: Code Review Etiquette

[lianilychee]

Overview

Context: We're trying to build consistency across our Labs product teams on PR quality and code review etiquette. This stems from one product team's bad experience in Spring 2025: A submitted PR took 6 weeks to review and merge, because both parties - the person who submitted the PR and the reviewer - had miscommunication, unclear expectations, and preconceived notions.

Desired outcomes from this work:

1. Reduced frustration in-the-moment for teammates trying to get a PR across the finish line
2. Establish consistent calibre and quality of products we build

Potential outputs:

• A list of what is expected after submitting a pull request
• This list might be translated into a linter, or a linter + google doc combo

This work is not:

• Creating PR template, since teams likely already have one
• Writing a guide to scoping/submitting a PR, since those guides definitely exist

Pre-requisites

• Have experience with submitting a PR and going through code review

Terminology

• PR != PR review
• PR review = code review
• Open Austin Lab team = Open Austin product team
  • We have 5 teams: Data Research Hub, APL, Landlord Mapper, NPDC, and OneBus

Action Items

It's really important to annotate as you go in this issue. That way, if you have to stop working on the issue, it's already up-to-date with your findings.

• Assign yourself to this ticket
• Read 3 different PR etiquette guides, for your own knowledge:
  • Example 1: Mike Pea's PR Etiquette guide
  • Example 2: "Code Review Etiquette" Reddit thread, specifically the comments by u/Icecoldkilluh and u/BenRegulus
  • Example 3: Cleiviane Costa's Code Review Etiquette article
• Fill in this table by gathering examples from other Open Austin product teams and practices:
  • APL product team (Julie Coleman on Slack)
  • NPDC product team (Darrell Malone on Slack)
  • Data/Dev community of practice

PR quality issues & norms	Code review issues & norms
* your finding	* your finding
* your finding	* your finding
* your finding	* your finding