Skip to main content

How Code Review Works

Type: ReferenceCreated: Team: Platform
draft

Before you open a pull request​

Code review starts before anyone else looks at your work. Once your branch is ready (see How We Branch and Commit), make sure it's in good shape on your own machine first:

  • The code builds without errors.
  • Formatting and linting pass — npm run format and npm run check-lint, or mvn spring-javaformat:apply for Java.
  • The tests run and pass, and you've added or updated tests for what you changed.

A pull request that fails formatting or linting won't be merged, so it's quicker to catch it here than after review.

Opening the pull request​

Open the pull request from your branch and fill in the template — don't delete its sections. The template asks you to:

  • Link the issue. Put the issue or ticket number in the TaskId line so the work is tied back to what it's for.
  • Write a summary. A short, plain description of what the change does and why.
  • Say how to test it. The steps a reviewer follows to see it working.

Then get it ready for someone to pick up:

  • Review it yourself first. Read your own diff top to bottom — you'll catch leftover debug code, stray comments, and obvious mistakes before a reviewer does.
  • Assign it to yourself.
  • Add the ready-for-code-review label. This is the signal that the PR is ready for someone to look at. Without it, reviewers don't know it's waiting.

Work the checklist in the template as you go — it's a reminder of the easy things to forget: tests written, formatting and linting run, no stray comments, and docs updated if your change affects them.

Who reviews it​

When you open a pull request, GitHub automatically requests a review from the repo's code owner, so you don't have to hunt for a reviewer.

note

Open question — who owns which part of the codebase isn't written down by area or team yet. The CODEOWNERS file currently points every change at a single maintainer rather than mapping areas to the teams that own them. Once that mapping exists, document here who reviews what — until then, don't assume a per-team reviewer.

Responding to review​

A reviewer may approve your change as-is, or ask for changes before it can merge. If they ask for changes, that's a normal part of the process — apply the requested changes on the same branch and push them. The pull request updates automatically, and the reviewer takes another look.

Keep the conversation on the pull request itself, so the reasoning behind a change stays with the code.

Before it can merge​

A pull request is ready to merge when:

  • Formatting and linting pass — a PR that fails these won't be merged.
  • The reviewer's requested changes have been made.
  • The reviewer approves it.

If you're fixing an issue, check that someone else hasn't already opened a pull request for the same thing first — we take the first viable change that resolves it.