Contribute to Samples

Blockly Samples contains extra content related to Blockly that isn't part of the core repository, including plugins, codelabs, and example code. For more details about each of these, see the Repository Structure page.

Need to Know

Here is a quick overview of facts about blockly-samples you need to know in order to create a PR.

  • The working branch is master and all PRs should be made against master.
  • Run npm install at the root level of blockly-samples, not at the individual plugin level. Blockly-samples is a monorepo, meaning it contains multiple packages in the same repository, and installing at the root level is part of the workflow for managing the monorepo with Lerna.
  • Code must conform to either Google's JavaScript Style Guide or TypeScript Style Guide depending on the language used.
  • Use conventional commits in your commit messages and pull request titles.

  • Any new code files must be prefixed with the Apache License v2.0:

    /**
 *   @license
 *   Copyright <Current YYYY> Google LLC
 *   SPDX-License-Identifier: Apache-2.0
 */

Make and Verify a Change

  1. Run npm install at the root level of blockly-samples to install dependencies.
  2. Run npm run start in a plugin's directory to build and start up a server running the plugin's test page. You can use this page to see the existing behavior of a plugin, or if you're adding a new plugin you will need to make this a useful test page so that others can see what your plugin does. See the playground page for more information.
  3. Make any necessary changes to the plugin's code.
  4. If you've left the server running, your changes will load automatically. Otherwise, restart the server and verify the plugin behaves as expected and there are no errors or warnings in the console.
  5. Run npm run build and ensure there are no build errors.
  6. Write automated mocha tests in the test/ directory.
  7. Run npm run test to run the automated tests.
  8. Run npm run lint:fix to fix lint errors. Address any remaining warnings or errors.
  9. Run npm run format to run the autoformatter.
  10. If all tests pass, you are ready to open a PR against master with your changes.