Skip to main content

Get started contributing to Blockly

Blockly is open source and is primarily maintained by a small team. We welcome contributions from developers outside the core team; there is no way for us to build every requested feature or fix every reported bug without our community.

info

This section contains general guides on contributing to Blockly. These guides are generally intended for those who are new to Blockly or new to open-source development.

For information specific to Blockly that you should read before making a contribution, see the Contributing to Core and Contributing to Samples sections.

Which repository?​

A repository contains all the files for a single project. Blockly has two repositories: blockly core and blockly-samples.

Blockly core is the repository for the Blockly library. Use this repository if you want to make a change to core Blockly behaviour in a way that will apply to all users of the library. Blockly core also contains the documentation, including the codelabs and codelab solutions.

Blockly samples is the repository for samples and plugins. Use this repository if you want to create or modify a plugin or a sample.

Pre work: Understand Git and GitHub basics​

We use Git and GitHub for managing version control, collaboration, and distribution of Blockly. If you're new to Git and GitHub, work through GitHub's quickstart tutorials to get comfortable with the basics.

To learn about the rest of Blockly's development tools, see the Contribute to Core documentation.

Setup​

These are the one-time setup steps you'll need to get started:

  1. Install Git and Node
  2. Fork and clone the repository. GitHub has a wonderful tutorial about forking a repo. To apply it to blockly, just replace every instance of octocat/Spoon-Knife with RaspberryPiFoundation/blockly or RaspberryPiFoundation/blockly-samples, depending on which repository you want to work in.

Step by step​

These are the general steps you will follow any time you make a change.

  1. Sync your fork. GitHub provides a tutorial for syncing a fork.
  2. Check out the main branch by running git checkout main in a terminal.
  3. Install dependencies and build tools by running npm install in the root directory.
  4. Create a new branch by running git checkout -b myBranchName in a terminal. The branch name should help you remember what you're working on.
  5. Make your changes.
  6. Validate your changes, following the guide for core or samples.
  7. Add your changes to a commit with git add your/file/path.
  8. Save your changes with git commit -m "fix: My commit message". Read more about commit messages.
  9. Push your changes to GitHub with git push origin myBranchName.
  10. Open a pull request when your code is ready. A member of the Blockly team will review your changes and merge them into Blockly if they are approved. For more information see PR Review Process.