Adding a first-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 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. Learn more...
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 should be added to the gh-pages/index.md file in the master branch of blockly-samples. This will cause them to appear on our Plugins site. First-party plugins should point to their test page. Third-party plugins can also be added to this page, and can point to a link of their owner's choosing, such as a hosted demo or the npm page.

Publishing

Finally, publishing. The Blockly team uses Lerna to manage versioning and publishing for all plugins.

Every Thursday, any plugins that have changed since their last release are published. If you need a change to be published sooner, please note it on your pull request.

The Plugins site is also updated whenever plugins are published.

Plugins that are not ready for publishing should be marked private in their package.json. This may happen if a plugin relies on a not-yet-published change in core Blockly. Core Blockly is published in the last week of each quarter (once every three months).