Skip to content

Adding A Plugin

Jump to bottom
Sam El-Husseini edited this page May 1, 2020 · 10 revisions

Introduction

A plugin is a self-contained piece of code that adds functionality to Blockly. Plugins can add fields, define themes, create renderers, and much more. The target user is a developer who finds and uses the plugin through npm. Plugins defined in this repository are first-party plugins, which means that they are supported by the Blockly team and published under the @blockly scope on npm. Third party plugins are maintained and published independently.

What makes a good plugin?

Great first party plugins have obvious use cases, are general-purpose, are stable, and are easy to use. Third party plugins may be more complex, more experimental, or more targeted.

For instance, a field for setting motor speed could be used in many robotics projects. On the other hand, a field for editing a specific object defined by your database schema is better as a third party plugin.

First party criteria

First party plugins must meet these requirements:

  • Works on all major platforms, unless granted an exemption by the Blockly team.
    • Chrome, Firefox, Safari, Edge
  • Has an author who is willing to handle bugs for the first year.
  • Does not monkeypatch Blockly.
  • Has a clearly defined and documented API.
  • Does not call private or package functions from Blockly core, unless granted an exemption by the Blockly team.
    • Overriding package functions on a subclass that you define is allowed.
  • Has tests.

If you think your idea would be a good fit for a plugin, you can follow the rest of this guide to suggest, design, implement, and publish it. And if your plugin isn't a good fit for first party, it may still be a great third party plugin!

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 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 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. This is done by Blockly team members when implementation is complete.

Clone this wiki locally