Skip to content

Adding A Plugin

Jump to bottom
Rachel Fenichel edited this page Apr 29, 2020 · 10 revisions

🚧 ⚠️ This page is under construction ⚠️ 🚧

🐙 Needs work: Clearer description of the expected results of the discussion phase. Checklists? New issue? Etc.

🐙 Needs work: Note that for multiple implementors, the Blockly team may open a feature branch.

Plugins are extremely powerful. They can:

  • add new field types (e.g. @blockly/field-slider, @blockly/field-date)
  • add or override block definitions (e.g. @blockly/blocks-plus-minus)
  • define themes
  • add UI widgets to workspaces
  • create renderers and much more!

Great plugins:

  • Have obvious use cases. For instance, toolbox search has been a community request for years, and would be eagerly adopted.
  • [TODO: expand]

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. To write a good suggestion:

  • Describe the desired functionality.
  • Describe the API the plugin would expose.
  • List alternatives you've considered.
  • List any APIs that need to be added or changed in core Blockly to support the plugin.
  • Include screenshots, GIFs, or mock-ups if the plugin includes UI features.
  • Explain why it should be a first-party plugin rather than a third-party plugin.

Before making a suggestion, search for a related issue. If you find one, add a comment to the existing issue instead of opening a new one.

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

Discussion

Next, a plugin will go 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 naming conventions that we will publish Real Soon Now.

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

Implementation may be done by multiple contributors in parallel. Anyone interested should comment on the issue and ask if it's still open for contributions. You may implement a plugin collaboratively on your own fork, or through pull requests against this repository. Plugins are not published while they are under initial construction.

Publishing

Finally, publishing. This is done by Blockly team members when implementation is complete.

Clone this wiki locally