---
description: The process a pull request goes through before being merged.
title: Code review process
image: images/blockly_banner.png
---

# Code review process

### Goals

Our review process has several goals:

- **Ensure high quality code**, in both functionality and readability.
- **Catch bugs**, because bugs happen.
- **Maintain consistent style** so that it's easy to start working in any part
  of the codebase.

All of the code that goes into
[blockly-samples](https://www.github.com/RaspberryPiFoundation/blockly-samples) and
[core Blockly](https://www.github.com/RaspberryPiFoundation/blockly) goes through review,
whether it's written by community contributors or Blockly team members.

As reviewers, we aim to work with you to make your change as good as possible.
We ask that you, as contributors, engage in conversation with us to get your
pull requests through review and merged.

# The Process

The PR review process goes through a few stages:

1. [Assignment](#assignment)
2. [Feedback](#feedback)
3. [Discussion](#discussion)
4. [Revision](#revision)
5. [Repetition](#repetition)
6. [Merge!](#merge)

## Assignment

When your pull request comes in, the on-call member of the Blockly team assigns
a reviewer.

Reviewers are chosen based on expertise and to evenly distribute workload.

It may take a few days to get a reviewer assigned, and a few more days to get a
review. Don't worry, this is normal.

## Feedback

During the feedback stage a reviewer leaves suggestions for changes on your PR.
These could be simple things to make your code conform to the
[Google JavaScript style guide](https://google.github.io/styleguide/jsguide.html).
Or they could be larger things like asking you to reorganize your function
definitions.

Reviewers are encouraged to use [GitHub's code
reviews](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/reviewing-proposed-changes-in-a-pull-request#starting-a-review) (rather
than making individual comments) so that you receive a single notification
instead of several.

## Discussion

The discussion phase is your chance to respond to the feedback. Maybe one
of the review comments wasn't clear: now is your chance to ask for
clarification. Or maybe your reviewer requested a change, but you think it will
have repercussions: now is your chance to find a compromise.

:::note
For this to work, both parties need to go into the discussion with a
spirit of **collaboration**. The goal is not to "win" but to make something
you're both proud of.
:::

## Revision

The revision phase is where you get to make changes to your PR. Usually these
changes are a result of something your reviewer has said in the feedback phase.

Once you have completed your revisions it can be helpful to [tag](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams)
your reviewer asking them to take another look.

:::note
discussion and revision may happen at the same time.
:::

## Repetition

After the revision phase your reviewer has another chance to give
[feedback](#feedback), and the process starts from the beginning.

Often a second review is simple and focuses on nits such as punctuation and code
style. But sometimes a second review can be quite big. Your first reviewer may
even ask someone else to take a look, to get a fresh perspective.

## Merge!

The merge phase is your chance to **celebrate**. You've created a change,
discussed and revised it, and finally gotten it merged! This is a grand
achievement that many people never start, let alone complete!

Thank you for all of your hard work to make Blockly better. And congratulations!
