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 and core 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:
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. Or they could be larger things like asking you to reorganize your function definitions.
Reviewers are encouraged to use GitHub's code reviews (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.
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 your reviewer asking them to take another look.
Repetition
After the revision phase your reviewer has another chance to give 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!