Development setup

Blockly uses some tools and libraries for development, including Git, npm, and the Closure Compiler. This section will provide some basic descriptions of each tool, as well as links to where you can find more information about each tool.

We use many of these tools through scripts. You may not need to ever run them directly. Knowing the names may still be helpful for debugging or filing issues or feature requests.

Tools

Git

Git is a version control system that we use to track and manage changes to files.

GitHub

GitHub is a hosting platform for version control, collaboration, and distribution of open-source code. Git tracks the files; GitHub provides smooth interfaces for reviewing code, tracking issues, and viewing change history.

Getting started: If you're new to Git and GitHub, work through GitHub's quickstart tutorials to get comfortable with the basics.

Node

Node.js is a way to run JavaScript on the server (rather than in a browser). npm (see below) runs on Node.

npm

npm is two things:

• A command-line tool that we use to install dependencies and run scripts.
• An online registry where we publish our code, which makes it easy for other developers to use Blockly.

Getting started: Install Node and npm.

Closure Compiler

The Closure Compiler is a tool for making JavaScript download and run faster. We use it to combine all of our JavaScript files into a single library; we also use it to check syntax and types.

Getting started: You don't need to install or run the Closure Compiler directly: we install and run it through npm.

Read more: Closure compiler documentation on JavaScript types and type annotations.

ESLint

ESLint is a static analyzer that finds problems with JavaScript code. We use it to define and enforce a consistent style across our codebase. Small problems with code (missing semicolons, inconsistent spacing, etc.) are often called lint. ESLint automatically runs when you send us a pull request. You can also run it locally.

Getting started: In both Blockly core and blockly-samples, you can run ESLint with npm run lint. Many code editors also have ESLint integrations to show problems as you type.

Read more: Each ESLint rule has a documentation page that describes the rule and gives examples of correct and incorrect code.

Mocha

Mocha is a JavaScript test framework. We use it to run tests in the browser and on Node.js (for headless use cases).

Getting started: In both Blockly core and blockly-samples, you can run our Mocha tests with npm run test. In Blockly core this will also run other tests. Blockly core's Mocha tests are defined in the tests/mocha directory.

Read more: Mocha allows developers to define hooks, which allow you to define centralized setup and teardown functions for your tests.

Chai

Chai is an assertion library that we use in our Mocha tests.

Read more: Chai has multiple "flavors" of syntax, to make it easy to integrate with existing projects. Blockly uses the assert flavor

Travis

Travis CI is a tool that automatically builds and tests every change that is submitted to Blockly on GitHub to help catch bugs and lint before merging. Travis automatically runs ESLint, our Mocha tests, and a variety of other tests.

Getting started: You don't need to install or run anything. You'll see status updates from Travis on your pull requests on GitHub.

Read more: Travis documentation on core concepts for beginners.

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. Fork 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.

Caution: In most cases you do not need to make a fork of Blockly to make your change. Read more about forking Blockly.

Blockly samples is the repository for samples, plugins, and codelabs. Fork this repository if you want to create or modify a plugin; write a codelab; or create or modify a sample.

Note: In blockly core all pull requests must be against develop. In blockly-samples all pull requests must be against master.

Step by step

If you've contributed to a GitHub repository before, the process for getting set up will be familiar to you.

If you haven't contributed to a GitHub project before, you can use these steps to get started:

1. Install Git and Node, following the links in the Tools section.
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 google/blockly or google/blockly-samples, depending on which repository you want to work in.
3. Sync your fork. GitHub provides a tutorial for syncing a fork as well.
4. Check out the main branch. In blockly core, this is the develop branch. In blockly-samples this is the master branch.
5. Install dependencies and build tools by running npm install in the root directory.
6. Create a new branch by running git checkout -b myBranchName in a terminal. The name should help you remember what you're working on.
7. Make your changes.
8. Save your changes with git commit -am "My commit message"
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 Contributing