Register for the online Blockly Developer Summit April 28-29, 2021!

Adding a first-party plugin

Read more about plugins

The process

Plugins go through four stages: suggestion, discussion, implementation, and publishing.

Suggestion

A plugin starts as a suggestion. You can suggest a plugin by creating a new issue with the Feature Request template.

Read up on how to write a feature request

In addition to the basic feature request information, a plugin suggestion should include:

  • The API the plugin would expose.
  • APIs that need to be added or changed in core Blockly to support the plugin.
  • Screenshots, GIFs, or mock-ups if the plugin includes UI features.
  • An explanation of why it should be a first-party plugin rather than a third-party plugin.

The Blockly team reviews suggestions as they come in and either closes the issue or adds the status: discussion label.

Discussion

Next, a plugin goes into the discussion phase. This phase includes:

  • Clarification of the desired functionality.
  • Clarification of the plugin's API.
  • Planning for implementation.
  • Planning for tests.
  • Discussion of API changes in core Blockly.
  • Breaking large plugins into implementation steps.
  • Plugin naming, based on our naming conventions.
  • Confirming all first party criteria will be met.

This discussion generally happens on the GitHub issue. The smaller the scope of the plugin, the faster the discussion phase can be. Larger plugins may attract community attention and strong opinions about the Right Solution. If this happens on your issue, congratulations! You have found something that people care about.

The goal is that at the end of the discussion phase, all major design decisions have been made and there is a clear list of implementation steps. Both should be documented in comments on the issue.

During discussion we may decide that a plugin should be a third-party plugin, and not be published under the @blockly scope. In that case we will explain why and close the issue.

When discussion is complete a Blockly team member adds the status: implementation label to the issue.

Implementation

Implementation steps include:

  • Running npx @blockly/create-package to set up the plugin and its directory from a template.
  • Implementing core logic for the plugin.
  • Implementing a UI, if needed.
  • Testing the plugin, using mocha.
  • Documenting the plugin, including the README.

If a plugin's issue has the status: implementation label, it is either ready for implementation or actively being implemented. To avoid duplicating efforts, anyone interested should comment on the issue and ask if it's still open for contributions.

Implementation may be done by multiple contributors in parallel. You may implement a plugin collaboratively on your own fork, or through pull requests against this repository. If you want to collaborate on a plugin in this repository, ask the Blockly team to create a feature branch for you.

Plugins are not published while they are under initial construction.

Publishing

Finally, publishing. The Blockly team publishes all public plugins in blockly-samples weekly, usually on a Thursday.