docs: update docs for monorepo

.github/ISSUE_TEMPLATE/config.yml

@@ -2,6 +2,6 @@ contact_links:
   - name: Ask a question ❓
     url: https://groups.google.com/forum/#!forum/blockly
     about: Go to the Blockly developer forum, where you can ask and answer questions.
-  - name: Report issues with plugins and examples 🧩
+  - name: Report issues with Blockly examples 🧩
     url: https://github.com/RaspberryPiFoundation/blockly-samples/issues/new/choose
-    about: File bugs or feature requests about plugins and samples in our blockly-samples repository.
+    about: File bugs or feature requests about samples in our blockly-samples repository.

README.md

@@ -35,7 +35,11 @@ npm install blockly
 
 ### blockly-samples
 
-We have a number of resources such as [examples](https://github.com/raspberrypifoundation/blockly-samples/tree/main/examples), [codelabs](https://github.com/raspberrypifoundation/blockly-samples/tree/main/codelabs), and [plugins](https://github.com/raspberrypifoundation/blockly-samples/tree/main/plugins) in another repository called [blockly-samples](https://github.com/raspberrypifoundation/blockly-samples). 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. For more information, see the [Plugins documentation](https://docs.blockly.com/guides/programming/plugin_overview/).
+We have a number of [examples](https://github.com/raspberrypifoundation/blockly-samples/tree/main/examples) which demonstrate various techniques to include and extend the Blockly library. These examples can be found in another repository called [blockly-samples](https://github.com/raspberrypifoundation/blockly-samples).
+
+### Plugins
+
+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. For more information, see the [Plugins documentation](https://docs.blockly.com/guides/programming/plugin_overview/).
 
 ## Contributing to Blockly
 

packages/blockly/scripts/package/README.md

@@ -26,7 +26,7 @@ Blockly.inject('blocklyDiv', {
 A [wide variety of plugins](https://raspberrypifoundation.github.io/blockly-samples/)
 that add additional features and functionality to Blockly are available. All
 plugins are distributed via NPM; source code can be found in the
-[Blockly Samples repo](http://github.com/RaspberryPiFoundation/blockly-samples).
+[Blockly repo](http://github.com/RaspberryPiFoundation/blockly).
 
 ## Installation
 

packages/docs/docs/guides/configure/appearance/themes.mdx

@@ -215,7 +215,7 @@ const theme = Blockly.Theme.defineTheme('themeName', {
 ```
 
 Here is an
-[example](https://github.com/RaspberryPiFoundation/blockly-samples/blob/aba88bea60bddf3d31ce630b836e2933836ed287/plugins/theme-dark/src/index.js#L21)
+[example](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/plugins/theme-dark/src/index.ts)
 of using `defineTheme`.
 
 ### Add Style Names

packages/docs/docs/guides/configure/metrics_manager.mdx

@@ -159,6 +159,6 @@ a substitute metrics manager object that implements the `IMetricsManager`
 interface or extends `Blockly.MetricsManager`.
 
 An example of this can be found in the [Continuous Toolbox
-plugin](https://github.com/RaspberryPiFoundation/blockly-samples/blob/main/plugins/continuous-toolbox/src/ContinuousMetrics.ts)
+plugin](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/plugins/continuous-toolbox/src/ContinuousMetrics.ts)
 or in the [Fixed Edges
-plugin](https://github.com/RaspberryPiFoundation/blockly-samples/blob/main/plugins/fixed-edges/src/index.js).
+plugin](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/plugins/fixed-edges/src/index.js).

packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx

@@ -0,0 +1,145 @@
+---
+description: The process for creating a plugin.
+title: Add a plugin
+image: images/blockly_banner.png
+---
+
+# Add a plugin
+
+This document discusses how to create a new plugin. While the process it
+describes is for creating first-party plugins, you can use it as a guideline for
+creating third-party plugins.
+
+For an overview of plugins,
+see [Plugins](/guides/programming/plugin_overview).
+
+For a quick introduction to creating a plugin, see our [How to Build a Plugin
+talk
+(2021)](https://www.youtube.com/watch?v=cZlZrTk2aQU&list=PLSIUOFhnxEiCjoIwJ0jAdwpTZET73CK7d&index=7).
+
+## First-party vs third-party
+
+The way that plugins are maintained falls into two categories:
+
+**First-party plugins** are:
+- Supported by the Blockly team.
+- Stored in the [blockly repository](https://github.com/RaspberryPiFoundation/blockly).
+- Published under the `@blockly` scope on npm.
+- Usable in a wide range of Blockly applications.
+- Stable, well-documented, and easy to use.
+
+:::note[Example]
+A field for setting motor speed could be used in many robotics projects and is a
+good candidate for a first-party plugin.
+::: 
+
+**Third-party plugins** are:
+- Maintained and published independently. 
+- More complex, more experimental, or targeted to a narrower range of Blockly applications. 
+
+:::note[Example]
+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:
+
+- Work on all major platforms, unless granted an exemption by the Blockly
+  team.
+  - Chrome, Firefox, Safari, Edge
+- Have an author who is willing to handle bugs for the first year.
+- Do not monkeypatch Blockly.
+- Have a clearly defined and documented API.
+- Do 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.
+  - If you want an exemption, ask us in an issue on blockly.
+- Have tests. 
+
+## The process
+
+Plugins go through three stages: [suggestion](#suggestion),
+ [implementation](#implementation), and
+[publishing](#publishing).
+
+## Suggestion
+
+A plugin starts as a **suggestion**. You can suggest a plugin by creating a new
+issue with the [Feature
+Request](https://github.com/RaspberryPiFoundation/blockly/issues/new?template=feature_request.yaml)
+template. For more information, read about [how to write a feature
+request](/guides/contribute/get-started/write_a_good_issue#feature-requests).
+
+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. On the GitHub issue, the 
+Blockly team will: 
+- Clarify the desired functionality of the plugin
+- Plan implementation steps and tests
+- Discuss API changes in core Blockly
+
+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.
+
+## Implementation
+
+Once a Blockly team member notes that the plugin is ready, implementation will 
+begin. 
+
+**Implementation** steps include:
+
+- Running `npx @blockly/create-package` to set up the plugin and its directory
+  from a template. [Learn
+  more...](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/plugins/dev-create)
+- Implementing the plugin.
+- Testing the plugin, using Mocha.
+- Documenting the plugin, including the `README`.
+
+If a suggested plugin has been approved for implementation and you would like to
+work on it, 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. 
+If you want to collaborate on a plugin, ask the Blockly team to create a feature 
+branch for you.
+
+Plugins should be added to the [`gh-pages/_index.html`](https://github.com/RaspberryPiFoundation/blockly-samples/blob/main/gh-pages/_index.html)
+file in the `main` branch of blockly-samples. This will cause them to appear
+on our [Plugins site](https://raspberrypifoundation.github.io/blockly-samples/). 
+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](https://lerna.js.org/) to
+manage versioning and publishing for all plugins. 
+
+Starting with Blockly v13, plugin version numbers match Blockly version numbers. 
+This means that:
+
+- You can easily know which version of a plugin is compatible with your specific
+version of Blockly. 
+- Plugin updates will be released when Blockly is released, unless the changes 
+are urgent enough to warrant a release of Blockly.  
+- Plugin version numbers may be incremented even when there are no changes to 
+the plugin's code.
+
+Note that Blockly uses [semantic versioning](https://semver.org/) to determine
+version numbers. 
+
+Plugins that are not ready for publishing should be marked `private` in their
+`package.json`. 
+
+The [plugins site](https://raspberrypifoundation.github.io/blockly-samples/index.html)
+will be updated whenever plugins are published.

packages/docs/docs/guides/contribute/samples/block_factory.mdx → packages/docs/docs/guides/contribute/core/plugins/block_factory.mdx

@@ -11,7 +11,7 @@ Tools](https://raspberrypifoundation.github.io/blockly-samples/examples/develope
 lets you create custom blocks using blocks! It has support for fields that are
 published as plugins in addition to the fields that come with core Blockly. If
 you've created a custom field, you can add support for it to the Block Factory
-by following this guide. The custom field must be published on npm before you
+by following this guide. The custom field must be **published on npm** before you
 can add support for it. You also need to commit to updating your field to keep
 up with changes in Blockly, otherwise we may need to remove it from Block
 Factory in the future.
@@ -22,17 +22,17 @@ The source code for the Block Factory is located in the blockly-samples
 repository in the [`examples/developer-tools`][source-developer-tools]
 directory.
 
-To submit a change to the Developer Tools in blockly-samples, you'll need to
+To submit a change to the Developer Tools, you'll need to
 follow the [typical steps][blockly-samples-development] for developing in
-blockly-samples. Unlike working with plugins however, you'll need to run `npm
-install` from the `examples/developer-tools` directory directly, rather than at
-the root level of blockly-samples.
+blockly-samples. Recall that you'll need to run `npm install` from the 
+`examples/developer-tools` directory directly, rather than at the root level of 
+blockly-samples
 
 ## Install the plugin
 
 In order for the Block Factory to show your custom field in the preview, it
 needs to install the custom field. Add your field as an npm dependency of
-developer-tools. Then, register it or do any other setup work necessary in
+developer-tools by including `package.json` for developer-tools. Then, register it or do any other setup work necessary in
 [`developer-tools/src/blocks/index.ts`][source-blocks-index].
 
 ## Create a block for the field

packages/docs/docs/guides/contribute/core/plugins/debugging.mdx

@@ -0,0 +1,37 @@
+---
+description: How to test changes in plugins that depend on changes in Blockly core.
+title: Debug plugins
+image: images/blockly_banner.png
+---
+
+# Debug plugins
+
+When debugging a plugin, you will need to follow a slightly different set of steps
+depending on where you have made changes.
+
+1. [You have only made changes to a plugin.](#making-changes-to-a-plugin)
+2. [You have made changes to a plugin which depend on corresponding changes to 
+Blockly core.](#making-changes-to-a-plugin-and-to-blockly-core)
+
+## Making changes to a plugin
+
+1. Run `npm install` from the root of the [blockly repo](https://github.com/RaspberryPiFoundation/blockly).
+1. Navigate to your plugin's directory (e.g. `cd /packages/plugins/my-favorite-plugin).
+1. Run `npm start` in the plugin's directory.
+
+## Making changes to a plugin and to blockly core
+
+Sometimes when developing a plugin for blockly, you'll need to make 
+corresponding changes in Blockly core (`/packages/blockly/`). To ensure that 
+your plugin is able to use the changes you've made in core Blockly, you should 
+first build blockly.
+
+1. Run `npm ci` from the root of the [blockly repo](https://github.com/RaspberryPiFoundation/blockly).
+1. Run `npm run build` from the root of the [blockly repo](https://github.com/RaspberryPiFoundation/blockly).
+1. Navigate to your plugin's directory (e.g. `cd /packages/plugins/my-favorite-plugin).
+1. Run `npm start` in the plugin's directory.
+
+:::tip
+If you make additional changes to Blockly core, you'll need to redo steps 2, 3, 
+and 4.
+:::

packages/docs/docs/guides/contribute/core/testing/playground.mdx

@@ -69,8 +69,7 @@ The playground features:
 ## Advanced playground
 
 The advanced playground contains additional features to make debugging Blockly
-even easier. This is also the default playground used in blockly-samples for all
-plugins.
+even easier. This is also the default playground used in blockly-samples.
 
 This playground features all of the simple playground features plus:
 
@@ -80,7 +79,7 @@ This playground features all of the simple playground features plus:
   playground is loaded.
 - See the output of each generator in the same window.
 
-To start the advanced playground for any plugin in blockly-samples, run `npm run
+To start the advanced playground for any plugin in blockly, run `npm run
 start` from the plugin's root directory. Currently, only one plugin can run at a
 time, and it uses port 3000. If you have trouble getting the plugin to start,
 first make sure nothing else is listening on that port.

packages/docs/docs/guides/contribute/core/testing/unit_testing.mdx

@@ -40,7 +40,7 @@ We have a number of helper functions specific to Blockly that may be useful when
 writing tests. These can be found in
 [core](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/blockly/tests/mocha/test_helpers/)
 and in
-[blockly-samples](https://github.com/RaspberryPiFoundation/blockly-samples/blob/main/plugins/dev-tools/src/test_helpers.mocha.js).
+[`@blockly/dev-tools`](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/plugins/dev-tools/src/test_helpers.mocha.js).
 
 The helper functions include `sharedTestSetup` and `sharedTestTeardown` which
 are **required** to be called before and after your tests (see Requirements

packages/docs/docs/guides/contribute/get-started/index.mdx

@@ -24,15 +24,17 @@ contribution, see the
 ## Which repository?
 
 A **repository** contains all the files for a single project. Blockly has two
-repositories: blockly core and blockly-samples.
+repositories: blockly and blockly-samples.
 
-**Blockly core** is the repository for the Blockly library. Use this repository
-if you want to make a change to core Blockly behaviour in a way that will apply
-to all users of the library. Blockly core also contains the documentation, including
-the codelabs and codelab solutions.
+**[Blockly](https://github.com/RaspberryPiFoundation/blockly)** is the 
+repository for the Blockly library. Use this repository if you want to make a 
+change to core Blockly behaviour in a way that will apply to all users of the 
+library. Blockly core also contains the documentation, including the codelabs 
+and codelab solutions.
 
-**Blockly samples** is the repository for samples and plugins. Use
-this repository if you want to create or modify a plugin or a sample.
+**[Blockly samples](https://github.com/raspberrypifoundation/blockly-samples)** 
+is the repository for examples that show uses of the Blockly library. Use this 
+repository if you want to create or modify a sample.
 
 ### Pre work: Understand Git and GitHub basics