We consider code reviews an essential practice of software engineering. Following the collective refinement of the task and one of the team taking up its implementation, the code review is the moment the work becomes collaborative again.
You open a pull request, explaining your approach and choices. Peers invest time in understanding the attempt and providing feedback. We document any emerging guidelines or decisions, do the work to resolve all comments, and integrate the increment into the product.
If you believe that the code in your branch meets the applicable acceptance criteria and the definition of done, you create a pull request (PR). If you have just pushed, a handy link will appear in the repo on github.com to create one immediately. Otherwise, you configure the new PR yourself.
Write an English title, avoiding jargon. This phrase should be easy to understand, as we use PR titles to compile release notes.
Clearly explain how you implemented the task. Be brief, e.g. by using a list. A reviewer will be able to find more context and details in the accompanying product backlog item.
If there are particular circumstances, original ways of tackling something, or things you have deliberately left out of scope, mention those as well. Instructions like steps to reproduce a bug or specific test data may also save the reviewer time.
Make sure that you designate the right people as reviewers. We want each PR to be approved by at least one of the maintainers.
As an author, you can start a discussion about a piece of code by commenting on it yourself. For example, you can indicate that you’d like feedback about a specific code fragment.
When saving the PR, GitHub will statically analyse the code for linting errors or failing tests.
Check back after a few minutes to verify there have been no errors – otherwise, the PR cannot merge, which will block the first reviewer.
Alternatively, run linting and tests locally: pnpm run lint and pnpm run test.
Creating a PR does not imply “My work is done, would you please look at it?”. Consider it more like: “This is my proposal for implementing the task. Let’s use our shared knowledge and complete the work together.”
If necessary, you can prepare the PR earlier; for example, to see a clear diff, have someone else watch or post comments or questions in advance. Then, put the PR in ‘draft’ mode so that no one receives notifications or thinks it is already time for the review.
Try to follow up on a pull request as quickly as possible. After all, we want to avoid long-living branches. The work will also be ‘top of mind’ for the author at the early stages. Make sure you receive notifications of new PRs in your name.
Invest the time to understand the PR change fully. Read the title and description carefully. Typically, you will check out the branch locally and test the functionality explicitly. Make yourself familiar with the new code as if you had written it yourself. Use our Definition of Done to verify that the work meets our quality standards.
Use GitHub’s ‘Start a review’ feature to ensure the author receives only one notification for all your comments.
Please realise that your written feedback may come across as more critical than you intended.
Your colleague has worked in good faith; make sure you communicate openly. Ask questions and make suggestions. “Would it be okay to…?” “Have you taken into account that…?” “I would expect such and such.”
Call each other if that is more convenient. And write a compliment if you come across some quality work.
Use GitHub’s suggestion feature to propose specific changes to code. Though you’ll still want to introduce the change, suggestions are often more straightforward than more prose. The author can apply or reject the proposal at the touch of a button.
In general, the author of a comment is the one to resolve it. This ensures the reviewer can perform a final check of the implemented changes, and the reviewer will see all merged code at least once. Comments created by AI tools are an exception to this rule. Make sure to check these yourself and resolve them once they are addressed.
If Chromatic indicates any visual changes in a submitted PR, review them yourself first. If any of these changes are undesirable, please submit another commit to correct it. If all visual changes are anticipated and acceptable, keep the visual diff open for the reviewer to examine. This allows the reviewer to conduct a final visual assessment of the changes made.
To run visual regression tests, comment /chromatic test on the pull request. This will trigger Chromatic to capture snapshots and compare them against the baseline. Visual regression tests also run automatically when a draft PR is marked as ready for review.
One of the maintainers approves the pull request if it meets the requirements and merges the branch. Static analysis must not reveal errors, all comments have been resolved, and enough reviewers have approved. Make sure there is no unnecessary waiting.
AI agents may author pull requests and review comments. The same conventions apply: PR titles follow Conventional Commits, descriptions explain the approach, and code meets the definition of done.
When reviewing a PR that was authored with AI assistance, pay extra attention to:
- Generated code that compiles but does not match project conventions or introduces subtle accessibility regressions.
- Overly broad changes — AI tools tend to refactor beyond the scope of the task.
When acting on review comments left by AI tools:
- Verify each suggestion against the codebase before applying it — AI tools can hallucinate APIs, file paths, or conventions.
- The comment author resolves their own comments, except for AI-generated comments. The PR author is responsible for checking and resolving those (see Resolve comments).