Skip to main content

Write a good pull request

Pull requests (PRs) are requests to merge new code into the repository. They keep everything healthy and moving. This page details how to create a PR that is complete and easy to review, which makes it more likely that your PR will get merged.

If this is your first time contributing to Blockly or blockly-samples, start at the development setup page.

Here are steps you can take to make sure you create the best PR possible:

  1. Communicate
  2. Keep it small
  3. Keep it clean
  4. Test your changes
  5. Write a summary
  6. Read the review
  7. Discuss, revise, and repeat
  8. Merge!

Communicate​

Before you jump in and start writing code, it's helpful to communicate with the team so they know what you're interested in. If there is an issue that you are interested in, put a comment on the issue saying you're going to start to work on it. A team member will respond to confirm that it's yours.

If you're not sure where to start, use the good first issue label to find issues that are good candidates for your first contribution to Blockly.

If you have an idea which is not covered by an issue, please write one up before you begin work. This gives the team a chance to discuss how best to build out the change before you start building.

Keep it Small​

Keep your changes small and focused. Some good rules of thumb are:

  • Fix one problem. Don't try to tackle multiple issues at once.
  • Use commits. If your PR feels a little big, split the changes into logical groups using git commits.

Keep it clean​

Why care about code style? We're in it for the long term, and consistent style makes maintenance easier. Style refers to how you name your variables, but also covers how you structure your code, write comments, and more. Where possible we use tools such as eslint to automate style checks.

In addition to eslint, please follow these guides:

Test your changes​

Before you put up a PR, you should always test that your changes are working. That way, you don't have to go back and fix things later. You should write unit tests covering your changes. You should also test your demonstrated functionality on the playground.

Write a summary​

After finishing the code, you'll need to create the PR. During the PR creation process, you'll write a summary describing your changes. Writing a great PR summary helps other developers review your changes, making it more likely that it will get accepted faster!

If you use an LLM to assist with writing your PR, we encourage you to edit the PR for length and clarity. LLMs tend to write lengthy PR descriptions, making them harder to review.

If you follow the PR template when your create your request you should be good to go. Just remember to be as concise and complete as possible.

Read the review​

After your PR is submitted, it will be reviewed by a member of the Blockly team. 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. All code is reviewed, regardless of whether it is written by community contributors or Blockly team members.

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.

Discuss, revise, and repeat​

Reviewers will leave comments on your PR. They may suggest changes or ask questions about the code you've written. You're welcome to ask for clarification, explain your choices, or point out issues with a requested change.

Be collaborative!

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.

Once you and your reviewer(s) have determined next steps, you can make revisions to your PR. GitHub will automatically update your PR if you push new commits on the same branch.

After revision, your reviewer may have more comments; this is completely normal! You'll repeat this process together until the PR is approved.

Merge!​

Once the PR is approved, a member of the Blockly team will merge it. The merge phase is your chance to celebrate. You've created a change, discussed and revised it, and finally gotten it merged!

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