Open Guide - Dev CoP: Code Review Etiquette #456
Description
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:
- Reduced frustration in-the-moment for teammates trying to get a PR across the finish line
- 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 |