From e3440d71c42e4a90809f6178ef49ab45133f9c97 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zo=C3=AB=20Spriggs?= Date: Fri, 7 Aug 2026 10:56:33 -0400 Subject: [PATCH 1/7] docs: wip plugins reorg --- .../plugins}/add_a_plugin.mdx | 75 ++++++++++++--- .../plugins}/block_factory.mdx | 9 +- .../plugins}/block_libraries.mdx | 0 .../{samples => core/plugins}/debugging.mdx | 0 .../{samples => core/plugins}/naming.mdx | 0 .../plugins}/repository_structure.mdx | 0 .../docs/docs/guides/contribute/samples.mdx | 94 +++++++++++++++++++ .../docs/guides/contribute/samples/index.mdx | 62 ------------ packages/docs/sidebars.js | 36 +++---- 9 files changed, 178 insertions(+), 98 deletions(-) rename packages/docs/docs/guides/contribute/{samples => core/plugins}/add_a_plugin.mdx (68%) rename packages/docs/docs/guides/contribute/{samples => core/plugins}/block_factory.mdx (97%) rename packages/docs/docs/guides/contribute/{samples => core/plugins}/block_libraries.mdx (100%) rename packages/docs/docs/guides/contribute/{samples => core/plugins}/debugging.mdx (100%) rename packages/docs/docs/guides/contribute/{samples => core/plugins}/naming.mdx (100%) rename packages/docs/docs/guides/contribute/{samples => core/plugins}/repository_structure.mdx (100%) create mode 100644 packages/docs/docs/guides/contribute/samples.mdx delete mode 100644 packages/docs/docs/guides/contribute/samples/index.mdx diff --git a/packages/docs/docs/guides/contribute/samples/add_a_plugin.mdx b/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx similarity index 68% rename from packages/docs/docs/guides/contribute/samples/add_a_plugin.mdx rename to packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx index d8def83c60e..d368e39d561 100644 --- a/packages/docs/docs/guides/contribute/samples/add_a_plugin.mdx +++ b/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx @@ -22,18 +22,67 @@ talk The target user for a plugin is a developer who finds and uses the plugin through npm. -First-party plugins are supported by the Blockly team and published under the +The way that plugins are maintained falls into two categories: + +- *First-party plugins* are supported by the Blockly team and published under the `@blockly` scope on npm. They are designed to be usable in a wide range of Blockly applications and are stable and easy to use. They are stored in the -[blockly-samples](https://github.com/RaspberryPiFoundation/blockly-samples). A field for -setting motor speed could be used in many robotics projects and is a good -candidate for a first-party plugin. +[blockly repository](https://github.com/RaspberryPiFoundation/blockly-samples). +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. They may be more +- *Third-party plugins* are maintained and published independently. They may be more complex, more experimental, or targeted to a narrower range of Blockly applications. A field for editing a specific object defined by your database schema is better as a third-party plugin. +## 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-samples). +- Published under the `@blockly` scope on npm. +- Usable in a wide range of Blockly applications. +- Stable and well-documented. + +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. + +A field for editing a specific object defined by your database schema is better +as a third-party plugin. + +## First-party vs third-party + +The way that plugins are maintained falls into two categories: first-party and +third-party. + +### First-party plugins + +**First-party plugins** are: +- Supported by the Blockly team. +- Stored in the [blockly repository](https://github.com/RaspberryPiFoundation/blockly-samples). +- Published under the `@blockly` scope on npm. +- Usable in a wide range of Blockly applications. +- Stable and well-documented. + +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 + +**Third-party plugins** are: +- Maintained and published independently. +- More complex, more experimental, or targeted to a narrower range of Blockly applications. + +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: @@ -60,7 +109,7 @@ Plugins go through four stages: [suggestion](#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-samples/issues/new?assignees=&labels=type%3A+feature+request%2C+triage&template=feature_request.yaml) +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). @@ -82,16 +131,13 @@ 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. +- Planning the implementation steps and tests. - Discussion of API changes in core Blockly. -- Breaking large plugins into implementation steps. - Plugin naming, based on our [naming conventions](/guides/contribute/samples/naming). - Confirming all [first party criteria](#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 +This discussion generally happens on the GitHub issue. 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. @@ -113,7 +159,7 @@ implemented. - Running `npx @blockly/create-package` to set up the plugin and its directory from a template. [Learn - more...](https://github.com/RaspberryPiFoundation/blockly-samples/tree/main/plugins/dev-create) + more...](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/plugins/dev-create) - Implementing core logic for the plugin. - Implementing a UI, if needed. - Testing the plugin, using Mocha. @@ -127,6 +173,8 @@ 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. +TODO: do we want to do the above? make development branches for plugins on main + 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 @@ -149,3 +197,6 @@ 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](https://github.com/RaspberryPiFoundation/blockly). Core Blockly is published in the last week of each quarter (once every three months). + +TODO: This whole section needs to be updated +TODO: are we still going to use Lerna? diff --git a/packages/docs/docs/guides/contribute/samples/block_factory.mdx b/packages/docs/docs/guides/contribute/core/plugins/block_factory.mdx similarity index 97% rename from packages/docs/docs/guides/contribute/samples/block_factory.mdx rename to packages/docs/docs/guides/contribute/core/plugins/block_factory.mdx index a5a5f111bac..158d5fcb3e6 100644 --- a/packages/docs/docs/guides/contribute/samples/block_factory.mdx +++ b/packages/docs/docs/guides/contribute/core/plugins/block_factory.mdx @@ -18,16 +18,19 @@ Factory in the future. ## Development on the Block Factory -The source code for the Block Factory is located in the blockly-samples -repository in the [`examples/developer-tools`][source-developer-tools] +The source code for the Block Factory is located in the blockly +repository in the [`packages/plugins/dev-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. +TODO: is this correct that you want to run npm install at the dev-tools level or +at the repo root level + ## Install the plugin In order for the Block Factory to show your custom field in the preview, it diff --git a/packages/docs/docs/guides/contribute/samples/block_libraries.mdx b/packages/docs/docs/guides/contribute/core/plugins/block_libraries.mdx similarity index 100% rename from packages/docs/docs/guides/contribute/samples/block_libraries.mdx rename to packages/docs/docs/guides/contribute/core/plugins/block_libraries.mdx diff --git a/packages/docs/docs/guides/contribute/samples/debugging.mdx b/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx similarity index 100% rename from packages/docs/docs/guides/contribute/samples/debugging.mdx rename to packages/docs/docs/guides/contribute/core/plugins/debugging.mdx diff --git a/packages/docs/docs/guides/contribute/samples/naming.mdx b/packages/docs/docs/guides/contribute/core/plugins/naming.mdx similarity index 100% rename from packages/docs/docs/guides/contribute/samples/naming.mdx rename to packages/docs/docs/guides/contribute/core/plugins/naming.mdx diff --git a/packages/docs/docs/guides/contribute/samples/repository_structure.mdx b/packages/docs/docs/guides/contribute/core/plugins/repository_structure.mdx similarity index 100% rename from packages/docs/docs/guides/contribute/samples/repository_structure.mdx rename to packages/docs/docs/guides/contribute/core/plugins/repository_structure.mdx diff --git a/packages/docs/docs/guides/contribute/samples.mdx b/packages/docs/docs/guides/contribute/samples.mdx new file mode 100644 index 00000000000..9c0b8b1aeb2 --- /dev/null +++ b/packages/docs/docs/guides/contribute/samples.mdx @@ -0,0 +1,94 @@ +--- +description: Learn how to contribute changes to Blockly Samples. +title: Contribute to samples +image: images/blockly_banner.png +--- + +# Blockly samples + +The [blockly-samples](https://github.com/RaspberryPiFoundation/blockly-samples) +respository contains extra content related to Blockly that isn't part of the +core repository. There are two main pieces of blockly-samples: + +1. [Examples](#examples) +1. [GitHub Pages](#github-pages) + +## Examples + +Examples are self-contained sample projects demonstrating techniques to include +and extend the Blockly library. They usually consist of a demo web page, and +some supporting code. While codelab walk you through building something +step-by-step, Examples show you a finished product, and allow you to explore it +at your own pace. + +![Screenshot of the blockly-react example](/images/structure-examples.png) + +Example code is meant to be extremely well-commented so that it is easy to copy. +The target user may be reading the code, running it locally, or copying code +snippets. + +The +[examples directory](https://github.com/RaspberryPiFoundation/blockly-samples/tree/main/examples) +has one folder per example. Each example can be run with `npm install && npm run +start`, and has a `README.md` file with additional context or instructions. + +## GitHub Pages + +Blockly-samples has a [webpage](https://raspberrypifoundation.github.io/blockly-samples/) where +many of the plugins and demos are available in a playground environment. This +page is hosted on GitHub pages, and the code for this site is in the +[gh-pages](https://github.com/RaspberryPiFoundation/blockly-samples/tree/main/gh-pages) +directory of blockly-samples. This directory contains templates for the pages on +the site. The actual site content is generated based on these templates and +metadata from each plugin or example hosted. + +# Contribute to samples + +You can make contributions to blockly-samples in the form of updating examples, +adding your own examples, or making updates to the GitHub pages site. + +## Need to know + +Here is a quick overview of facts about blockly-samples you need to know in +order to create a PR. + +- The working branch is **main** and all PRs should be made against main. +- **Run `npm install` at the root level of blockly-samples,** not at the + individual plugin level. Blockly-samples is a monorepo, meaning it contains + multiple packages in the same repository, and installing at the root level + is part of the workflow for managing the monorepo with Lerna. +- Code must conform to either Google's [JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) + or [TypeScript Style + Guide](https://google.github.io/styleguide/tsguide.html) depending on the + language used. +- Use [conventional commits](/guides/contribute/get-started/commits) + in your commit messages and pull request titles. +- Any new code files must be prefixed with the Apache License v2.0: + + ```js + /** + * @license + * Copyright Raspberry Pi Foundation + * SPDX-License-Identifier: Apache-2.0 + */ + ``` + +## Make and Verify a Change + +1. Run `npm install` at the root level of blockly-samples to install + dependencies. +1. For examples, you can run `npm run start` in an example's directory to start + up a server running the example. For GitHub pages, you can run + `npm run test:ghpages` to launch the GitHub pages locally. +1. Make any necessary changes to the code. +1. If you've left the server running, your changes will load automatically. + Otherwise, restart the server and verify that everything behaves as expected + and there are no errors or warnings in the console. +1. Run `npm run build` and ensure there are no build errors. +1. Write automated mocha tests in the `test/` directory. +1. If applicable, run `npm run test` to run the automated tests. +1. Run `npm run lint:fix` to fix lint errors. Address any remaining warnings or + errors. +1. Run `npm run format` to run the autoformatter. +1. If all tests pass, you are ready to open a PR against **main** with your + changes. diff --git a/packages/docs/docs/guides/contribute/samples/index.mdx b/packages/docs/docs/guides/contribute/samples/index.mdx deleted file mode 100644 index c7a1cf9981e..00000000000 --- a/packages/docs/docs/guides/contribute/samples/index.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -description: Learn how to contribute changes to Blockly Samples. -title: Contribute to samples -image: images/blockly_banner.png ---- - -# Contribute to samples - -[Blockly samples](https://github.com/RaspberryPiFoundation/blockly-samples) contains extra -content related to Blockly that isn't part of the core repository, including -plugins and example code. For more details about each of these, see -the [Repository -Structure](/guides/contribute/samples/repository_structure) page. - -## Need to Know - -Here is a quick overview of facts about blockly-samples you need to know in -order to create a PR. - -- The working branch is **main** and all PRs should be made against main. -- **Run `npm install` at the root level of blockly-samples,** not at the - individual plugin level. Blockly-samples is a monorepo, meaning it contains - multiple packages in the same repository, and installing at the root level - is part of the workflow for managing the monorepo with Lerna. -- Code must conform to either Google's [JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) - or [TypeScript Style - Guide](https://google.github.io/styleguide/tsguide.html) depending on the - language used. -- Use [conventional commits](/guides/contribute/get-started/commits) - in your commit messages and pull request titles. -- Any new code files must be prefixed with the Apache License v2.0: - - ```js - /** - * @license - * Copyright Raspberry Pi Foundation - * SPDX-License-Identifier: Apache-2.0 - */ - ``` - -## Make and Verify a Change - -1. Run `npm install` at the root level of blockly-samples to install - dependencies. -1. Run `npm run start` in a plugin's directory to build and start up a server - running the plugin's test page. You can use this page to see the existing - behavior of a plugin, or if you're adding a new plugin you will need to make - this a useful test page so that others can see what your plugin does. See - the [playground](/guides/contribute/get-started/playground) page for - more information. -1. Make any necessary changes to the plugin's code. -1. If you've left the server running, your changes will load automatically. - Otherwise, restart the server and verify the plugin behaves as expected and - there are no errors or warnings in the console. -1. Run `npm run build` and ensure there are no build errors. -1. Write automated mocha tests in the `test/` directory. -1. Run `npm run test` to run the automated tests. -1. Run `npm run lint:fix` to fix lint errors. Address any remaining warnings or - errors. -1. Run `npm run format` to run the autoformatter. -1. If all tests pass, you are ready to open a PR against **main** with your - changes. diff --git a/packages/docs/sidebars.js b/packages/docs/sidebars.js index b0681c7c980..0f89ff0d5ad 100644 --- a/packages/docs/sidebars.js +++ b/packages/docs/sidebars.js @@ -1428,55 +1428,49 @@ const sidebars = { label: 'Write a codelab', id: 'guides/contribute/core/write_a_codelab', }, - ], - }, - { - type: 'category', - label: 'Contribute to samples', - items: [ - { - type: 'doc', - label: 'Overview', - id: 'guides/contribute/samples/index', - }, - { - type: 'doc', - label: 'Repository structure', - id: 'guides/contribute/samples/repository_structure', - }, { type: 'category', label: 'Plugins', items: [ + { + type: 'doc', + label: 'Repository structure', + id: 'guides/contribute/core/plugins/repository_structure', + }, { type: 'doc', label: 'Add a plugin', - id: 'guides/contribute/samples/add_a_plugin', + id: 'guides/contribute/core/plugins/add_a_plugin', }, { type: 'doc', label: 'Plugin naming conventions', - id: 'guides/contribute/samples/naming', + id: 'guides/contribute/core/plugins/naming', }, { type: 'doc', label: 'Debug plugins', - id: 'guides/contribute/samples/debugging', + id: 'guides/contribute/core/plugins/debugging', }, { type: 'doc', label: 'Publish block libraries', - id: 'guides/contribute/samples/block_libraries', + id: 'guides/contribute/core/plugins/block_libraries', }, { type: 'doc', label: 'Add a plugin field to Block Factory', - id: 'guides/contribute/samples/block_factory', + id: 'guides/contribute/core/plugins/block_factory', }, ], }, ], }, + { + type: 'doc', + label: 'Contribute to samples', + id: 'guides/contribute/samples', + }, ], }, ], From 9251bb21fab2c30c9926bb06e6640cf1dde0498a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zo=C3=AB=20Spriggs?= Date: Mon, 10 Aug 2026 09:07:23 -0500 Subject: [PATCH 2/7] docs: wip continue updating docs --- .../contribute/core/plugins/add_a_plugin.mdx | 101 +++++------------- .../contribute/core/plugins/block_factory.mdx | 15 ++- .../contribute/core/plugins/debugging.mdx | 2 + .../core/plugins/repository_structure.mdx | 57 ---------- .../guides/programming/plugin_overview.mdx | 50 ++++++--- packages/docs/sidebars.js | 5 - 6 files changed, 72 insertions(+), 158 deletions(-) delete mode 100644 packages/docs/docs/guides/contribute/core/plugins/repository_structure.mdx diff --git a/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx b/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx index d368e39d561..33d94455166 100644 --- a/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx +++ b/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx @@ -19,25 +19,6 @@ talk ## First-party vs third-party -The target user for a plugin is a developer who finds and uses the plugin -through npm. - -The way that plugins are maintained falls into two categories: - -- *First-party plugins* are supported by the Blockly team and published under the -`@blockly` scope on npm. They are designed to be usable in a wide range of -Blockly applications and are stable and easy to use. They are stored in the -[blockly repository](https://github.com/RaspberryPiFoundation/blockly-samples). -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. They may be more -complex, more experimental, or targeted to a narrower range of Blockly -applications. A field for editing a specific object defined by your database -schema is better as a third-party plugin. - -## First-party vs third-party - The way that plugins are maintained falls into two categories: **First-party plugins** are: @@ -45,43 +26,21 @@ The way that plugins are maintained falls into two categories: - Stored in the [blockly repository](https://github.com/RaspberryPiFoundation/blockly-samples). - Published under the `@blockly` scope on npm. - Usable in a wide range of Blockly applications. -- Stable and well-documented. +- 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 vs third-party - -The way that plugins are maintained falls into two categories: first-party and -third-party. - -### First-party plugins - -**First-party plugins** are: -- Supported by the Blockly team. -- Stored in the [blockly repository](https://github.com/RaspberryPiFoundation/blockly-samples). -- Published under the `@blockly` scope on npm. -- Usable in a wide range of Blockly applications. -- Stable and well-documented. - -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 - -**Third-party plugins** are: -- Maintained and published independently. -- More complex, more experimental, or targeted to a narrower range of Blockly applications. - -A field for editing a specific object defined by your database schema is better -as a third-party plugin. +::: ### First party criteria @@ -127,25 +86,16 @@ or agrees that it would be a good first-party plugin. ## Discussion -Next, a plugin goes into the **discussion** phase. This phase includes: +Next, a plugin goes into the **discussion** phase. This phase generally occurs +on the GitHub issue, and includes: -- Clarification of the desired functionality. -- Clarification of the plugin's API. +- Clarification of the desired functionality and the plugin's API. - Planning the implementation steps and tests. - Discussion of API changes in core Blockly. - Plugin naming, based on our [naming conventions](/guides/contribute/samples/naming). - Confirming all [first party criteria](#first-party-criteria) will be met. -This discussion generally happens on the GitHub issue. 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. @@ -177,26 +127,33 @@ TODO: do we want to do the above? make development branches for plugins on main 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. +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. +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. +Starting with Blockly v13, plugin version numbers match Blockly version numbers. +This means that: -The Plugins site is also updated whenever plugins are published. +- 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`. This may happen if a plugin relies on a not-yet-published change -in [core Blockly](https://github.com/RaspberryPiFoundation/blockly). Core Blockly is published -in the last week of each quarter (once every three months). +`package.json`. + -TODO: This whole section needs to be updated -TODO: are we still going to use Lerna? + +The Plugins site is also updated whenever plugins are published. +TODO: I think this isn't true diff --git a/packages/docs/docs/guides/contribute/core/plugins/block_factory.mdx b/packages/docs/docs/guides/contribute/core/plugins/block_factory.mdx index 158d5fcb3e6..a1d4f0980bb 100644 --- a/packages/docs/docs/guides/contribute/core/plugins/block_factory.mdx +++ b/packages/docs/docs/guides/contribute/core/plugins/block_factory.mdx @@ -11,31 +11,28 @@ 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. ## Development on the Block Factory -The source code for the Block Factory is located in the blockly +The source code for the Block Factory is located in the blockly-samples repository in the [`packages/plugins/dev-tools`][source-developer-tools] directory. 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. - -TODO: is this correct that you want to run npm install at the dev-tools level or -at the repo root level +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 diff --git a/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx b/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx index fed54024271..91b3efa3a91 100644 --- a/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx +++ b/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx @@ -6,6 +6,8 @@ image: images/blockly_banner.png # Debug plugins +TODO: This should be able to be deleted once NX is fully set up. Leaving here for now, because there could still maybe be special instructions after nx is set up + Sometimes when developing a plugin in blockly-samples, you'll need to make corresponding changes in Blockly itself. Most plugins are set up to fetch Blockly from the npm registry, so you'd only be able to use code that has diff --git a/packages/docs/docs/guides/contribute/core/plugins/repository_structure.mdx b/packages/docs/docs/guides/contribute/core/plugins/repository_structure.mdx deleted file mode 100644 index b6e990b3a6b..00000000000 --- a/packages/docs/docs/guides/contribute/core/plugins/repository_structure.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -description: The types of content available in blockly-samples. -title: Repository structure -image: images/blockly_banner.png ---- - -# Repository structure - -The blockly-samples repository contains a few different categories of projects. -This page is meant to help you understand where the different categories live, -and what each project in a category might contain. - -### Examples - -Examples are self-contained sample projects demonstrating techniques to include -and extend the Blockly library. They usually consist of a demo web page, and -some supporting code. While codelab walk you through building something -step-by-step, Examples show you a finished product, and allow you to explore it -at your own pace. - -![Screenshot of the blockly-react example](/images/structure-examples.png) - -Example code is meant to be extremely well-commented so that it is easy to copy. -The target user may be reading the code, running it locally, or copying code -snippets. - -The -[examples directory](https://github.com/RaspberryPiFoundation/blockly-samples/tree/main/examples) -has one folder per example. Each example can be run with `npm install && npm run -start`, and has a `README.md` file with additional context or instructions. - -### Plugins - -Plugins are self-contained pieces of code that add 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. - -![Screenshot of the "typed variable modal" plugin](/images/structure-plugin.png) - -The -[plugins directory](https://github.com/RaspberryPiFoundation/blockly-samples/tree/main/plugins) -has one folder per plugin. Each plugin has a `src` directory, where the code is -contained, and a `test` directory, where a demo page lives. They also contain a -`README.md` file, which gives developers information about what the plugin does, -and how to use it. - -### Github Pages - -Blockly-samples has a [webpage](https://raspberrypifoundation.github.io/blockly-samples/) where -many of the plugins and demos are available in a playground environment. This -page is hosted on GitHub pages, and the code for this site is in the -[gh-pages](https://github.com/RaspberryPiFoundation/blockly-samples/tree/main/gh-pages) -directory of blockly-samples. This directory contains templates for the pages on -the site. The actual site content is generated based on these templates and -metadata from each plugin or example hosted. diff --git a/packages/docs/docs/guides/programming/plugin_overview.mdx b/packages/docs/docs/guides/programming/plugin_overview.mdx index 92ee2758b26..0b308013ae4 100644 --- a/packages/docs/docs/guides/programming/plugin_overview.mdx +++ b/packages/docs/docs/guides/programming/plugin_overview.mdx @@ -52,10 +52,9 @@ applications. [`keyword:blockly`](https://www.npmjs.com/search?q=keyword%3Ablockly) or [`blockly`](https://www.npmjs.com/search?q=blockly). -* See the [`blockly-samples/plugins` - directory](https://github.com/RaspberryPiFoundation/blockly-samples/tree/main/plugins) on - GitHub, which is the repository for first-party plugins. Each plugin has a - README that describes its behaviour and intended use. +* See the [`packages/plugins/`](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/plugins) + directory on GitHub, which is the location of first-party plugins. + Each plugin has a README that describes its behaviour and intended use. ## Install a plugin @@ -84,7 +83,7 @@ makes it easy to receive updates. You can also clone the GitHub repository that contains the plugin. For first-party plugins, this is - [`blockly-samples`](https://github.com/RaspberryPiFoundation/blockly-samples/tree/main). + [`blockly`](https://github.com/RaspberryPiFoundation/blockly/tree/main). @@ -148,8 +147,10 @@ plugin](https://www.npmjs.com/package/@blockly/field-angle): ## Plugin versions -Plugins in `blockly-samples` use [semantic versioning](https://semver.org), -which requires breaking changes to use a new major version. Any new plugin that +Blockly uses [semantic versioning](https://semver.org), which requires breaking +changes to use a new major version. + +Any new plugin that monkey patches core will have a major version of 0 to [signify initial development](https://semver.org/#spec-item-4). @@ -157,21 +158,40 @@ Most plugins include the `blockly` package as a [`peerDependency`](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#peerdependencies) rather than a `dependency`. This is because we assume that you have already installed Blockly. (It doesn't make sense to use a plugin without using -Blockly.) This lets you manage the Blockly version yourself, but also requires -you to check the plugin's `package.json` to determine the minimum version of -Blockly it requires. If a plugin is updated to need a newer version of Blockly, -this is considered a breaking change and its major version will be increased. +Blockly.) Starting with Blockly v13, first-party plugins share an exact version +number with core Blockly. This means that in order to use a certain plugin, all +you can simply check your Blockly version and use the same plugin version. + +
+What if I'm using a major version of Blockly that's older than v13? + +Keeping Blockly up-to-date is strongly reccomended, so that you get the newest +features and fixes. However, if you can't upgrade Blockly, you can use the +following npm command to list all of the pre-v13 versions of a plugin alongside +the minimum Blockly version that they support: + +``` +npm view '@blockly/block-plus-minus@<13' peerDependencies.blockly +``` + +Just replace block-plus-minus with the name of whichever plugin you'd like to +use. + +
When you add a plugin to your application's `package.json`, the default is to include a caret before the version: ```json "dependencies": { - "@blockly/field-angle": "^5.0.12" + "@blockly/field-angle": "^13.2.1" } ``` This will let npm install any minor version at or above the listed version, so -version `5.0.20` or `5.1.0` works, but a new major version such as `6.0.1` does -not. When you update to a new version of Blockly, it's a good idea to check if -any of your plugins can be updated to a new major version as well. +version `13.3.1` or `13.2.6` works, but a new major version such as `14.0.1` would +not. When you update to a major version of Blockly, you should update your plugins +as well. + +TODO: but would npm handle the plugin updates automatically if you bump the blockly +major version? how would that workflow look? diff --git a/packages/docs/sidebars.js b/packages/docs/sidebars.js index 0f89ff0d5ad..9a04df12a34 100644 --- a/packages/docs/sidebars.js +++ b/packages/docs/sidebars.js @@ -1432,11 +1432,6 @@ const sidebars = { type: 'category', label: 'Plugins', items: [ - { - type: 'doc', - label: 'Repository structure', - id: 'guides/contribute/core/plugins/repository_structure', - }, { type: 'doc', label: 'Add a plugin', From 8b9b3533c30488a3ea23971b9c51f67e68a0616f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zo=C3=AB=20Spriggs?= Date: Wed, 12 Aug 2026 14:25:53 -0500 Subject: [PATCH 3/7] docs: audit mentions of blockly-samples --- .github/ISSUE_TEMPLATE/config.yml | 4 ++-- README.md | 6 +++++- packages/blockly/scripts/package/README.md | 2 +- packages/docs/docs/guides/configure/appearance/themes.mdx | 2 +- packages/docs/docs/guides/configure/metrics_manager.mdx | 4 ++-- .../docs/guides/contribute/core/plugins/add_a_plugin.mdx | 4 ++-- .../docs/guides/contribute/core/plugins/block_factory.mdx | 2 +- .../docs/guides/contribute/core/testing/playground.mdx | 6 +++--- .../docs/guides/contribute/core/testing/unit_testing.mdx | 2 +- .../docs/docs/guides/contribute/get-started/index.mdx | 4 ++-- packages/docs/docs/guides/contribute/samples.mdx | 8 +++----- .../create-custom-blocks/inputs/connection_checker.mdx | 2 +- .../docs/docs/guides/create-custom-blocks/mutators.mdx | 2 +- packages/docs/docs/guides/programming/forking_blockly.mdx | 3 ++- 14 files changed, 27 insertions(+), 24 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index f726e819876..08fa126c271 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.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. diff --git a/README.md b/README.md index c34a841f2a9..f037f24fbbd 100644 --- a/README.md +++ b/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 diff --git a/packages/blockly/scripts/package/README.md b/packages/blockly/scripts/package/README.md index c06a00f7ef0..4f08d907d97 100644 --- a/packages/blockly/scripts/package/README.md +++ b/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 diff --git a/packages/docs/docs/guides/configure/appearance/themes.mdx b/packages/docs/docs/guides/configure/appearance/themes.mdx index 6f841128d8e..9536121904e 100644 --- a/packages/docs/docs/guides/configure/appearance/themes.mdx +++ b/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 diff --git a/packages/docs/docs/guides/configure/metrics_manager.mdx b/packages/docs/docs/guides/configure/metrics_manager.mdx index aca7d968cd7..cf9e292af71 100644 --- a/packages/docs/docs/guides/configure/metrics_manager.mdx +++ b/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). diff --git a/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx b/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx index 33d94455166..f39f31d7884 100644 --- a/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx +++ b/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx @@ -23,7 +23,7 @@ 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-samples). +- 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. @@ -55,7 +55,7 @@ First party plugins **must** meet these requirements: - 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-samples. + - If you want an exemption, ask us in an issue on blockly. - Have tests. ## The process diff --git a/packages/docs/docs/guides/contribute/core/plugins/block_factory.mdx b/packages/docs/docs/guides/contribute/core/plugins/block_factory.mdx index a1d4f0980bb..dd64c92d517 100644 --- a/packages/docs/docs/guides/contribute/core/plugins/block_factory.mdx +++ b/packages/docs/docs/guides/contribute/core/plugins/block_factory.mdx @@ -19,7 +19,7 @@ Factory in the future. ## Development on the Block Factory The source code for the Block Factory is located in the blockly-samples -repository in the [`packages/plugins/dev-tools`][source-developer-tools] +repository in the [`examples/developer-tools`][source-developer-tools] directory. To submit a change to the Developer Tools, you'll need to diff --git a/packages/docs/docs/guides/contribute/core/testing/playground.mdx b/packages/docs/docs/guides/contribute/core/testing/playground.mdx index b404d575946..59ad02c87c9 100644 --- a/packages/docs/docs/guides/contribute/core/testing/playground.mdx +++ b/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,8 @@ 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 +TODO: double check, is this still how to start the advanced playground for a plugin? +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. diff --git a/packages/docs/docs/guides/contribute/core/testing/unit_testing.mdx b/packages/docs/docs/guides/contribute/core/testing/unit_testing.mdx index 9c19c3881e3..896e7da5afb 100644 --- a/packages/docs/docs/guides/contribute/core/testing/unit_testing.mdx +++ b/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 diff --git a/packages/docs/docs/guides/contribute/get-started/index.mdx b/packages/docs/docs/guides/contribute/get-started/index.mdx index 012909479d2..d4c5c8215b0 100644 --- a/packages/docs/docs/guides/contribute/get-started/index.mdx +++ b/packages/docs/docs/guides/contribute/get-started/index.mdx @@ -31,8 +31,8 @@ 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** 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 diff --git a/packages/docs/docs/guides/contribute/samples.mdx b/packages/docs/docs/guides/contribute/samples.mdx index 9c0b8b1aeb2..f289f7910b6 100644 --- a/packages/docs/docs/guides/contribute/samples.mdx +++ b/packages/docs/docs/guides/contribute/samples.mdx @@ -53,10 +53,9 @@ Here is a quick overview of facts about blockly-samples you need to know in order to create a PR. - The working branch is **main** and all PRs should be made against main. -- **Run `npm install` at the root level of blockly-samples,** not at the - individual plugin level. Blockly-samples is a monorepo, meaning it contains - multiple packages in the same repository, and installing at the root level - is part of the workflow for managing the monorepo with Lerna. +- **Run `npm install` at the root level of blockly-samples.** Blockly-samples is + a monorepo, meaning it contains multiple packages in the same repository, and + installing at the root level is part of the workflow for managing the monorepo with Lerna. - Code must conform to either Google's [JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) or [TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html) depending on the @@ -85,7 +84,6 @@ order to create a PR. Otherwise, restart the server and verify that everything behaves as expected and there are no errors or warnings in the console. 1. Run `npm run build` and ensure there are no build errors. -1. Write automated mocha tests in the `test/` directory. 1. If applicable, run `npm run test` to run the automated tests. 1. Run `npm run lint:fix` to fix lint errors. Address any remaining warnings or errors. diff --git a/packages/docs/docs/guides/create-custom-blocks/inputs/connection_checker.mdx b/packages/docs/docs/guides/create-custom-blocks/inputs/connection_checker.mdx index 30e1f31ea4a..fb5e7867eb9 100644 --- a/packages/docs/docs/guides/create-custom-blocks/inputs/connection_checker.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/inputs/connection_checker.mdx @@ -64,5 +64,5 @@ on your connection checker. ## Example code The [strict connection checker -plugin](https://github.com/RaspberryPiFoundation/blockly-samples/tree/main/plugins/strict-connection-checker) +plugin](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/plugins/strict-connection-checker) is a simple example of a custom checker. diff --git a/packages/docs/docs/guides/create-custom-blocks/mutators.mdx b/packages/docs/docs/guides/create-custom-blocks/mutators.mdx index 5239ee86d41..82e38917e48 100644 --- a/packages/docs/docs/guides/create-custom-blocks/mutators.mdx +++ b/packages/docs/docs/guides/create-custom-blocks/mutators.mdx @@ -159,7 +159,7 @@ else clauses to the if-do block.](/images/mutator-annot.png) You don't have to use this UI if you want to add extra serialization. You could use a custom UI, like the [blocks-plus-minus -plugin](https://github.com/RaspberryPiFoundation/blockly-samples/tree/main/plugins/block-plus-minus) +plugin](https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/plugins/block-plus-minus) provides, or you could use no UI at all! ### compose and decompose diff --git a/packages/docs/docs/guides/programming/forking_blockly.mdx b/packages/docs/docs/guides/programming/forking_blockly.mdx index ee19ee37a43..54947060d9f 100644 --- a/packages/docs/docs/guides/programming/forking_blockly.mdx +++ b/packages/docs/docs/guides/programming/forking_blockly.mdx @@ -29,7 +29,8 @@ code. ### Use an existing plugin If your change is a commonly requested feature, we may already have published it -as a plugin on blockly-samples. +as a plugin. Check the [plugins overview page](https://raspberrypifoundation.github.io/blockly-samples/#plugins) +to see plugin options. ### Write a plugin From e8da1e7d57e0416a3b07132710f1c0878aded5b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zo=C3=AB=20Spriggs?= Date: Mon, 24 Aug 2026 11:47:51 -0600 Subject: [PATCH 4/7] docs: finish plugins updates --- .../contribute/core/plugins/add_a_plugin.mdx | 6 +- .../contribute/core/plugins/debugging.mdx | 59 ++++++++----------- .../contribute/core/testing/playground.mdx | 1 - .../guides/programming/plugin_overview.mdx | 3 - 4 files changed, 24 insertions(+), 45 deletions(-) diff --git a/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx b/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx index f39f31d7884..f2fd8a867f4 100644 --- a/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx +++ b/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx @@ -57,6 +57,7 @@ First party plugins **must** meet these requirements: - 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. +TODO ## The process @@ -123,8 +124,6 @@ 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. -TODO: do we want to do the above? make development branches for plugins on main - 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/). @@ -153,7 +152,4 @@ version numbers. Plugins that are not ready for publishing should be marked `private` in their `package.json`. - - The Plugins site is also updated whenever plugins are published. -TODO: I think this isn't true diff --git a/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx b/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx index 91b3efa3a91..795088450dc 100644 --- a/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx +++ b/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx @@ -1,50 +1,37 @@ --- -description: How to test changes in blockly-samples that depend on changes in Blockly core. +description: How to test changes in plugins that depend on changes in Blockly core. title: Debug plugins image: images/blockly_banner.png --- # Debug plugins -TODO: This should be able to be deleted once NX is fully set up. Leaving here for now, because there could still maybe be special instructions after nx is set up +When debugging a plugin, you will need to follow a slightly different set of steps +depending on where you have made changes. -Sometimes when developing a plugin in blockly-samples, you'll need to make -corresponding changes in Blockly itself. Most plugins are set up to fetch -Blockly from the npm registry, so you'd only be able to use code that has -already been released on npm. This would make debugging your Blockly changes -difficult. When you want to make and test changes in both blockly and blockly- -samples, you can use `npm link` to test your unreleased changes together. +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) -## npm link +## Making changes to a plugin -You can tell npm to use a package from your machine instead of fetching the -package from the npm registry. Using this method, you should have access to -sourcemaps that make debugging blockly easier. You can use this method with -changes in core that haven't yet been pushed to GitHub. +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. -1. In your fork of blockly: +## Making changes to a plugin and to blockly core - ```shell - $ npm run package - $ cd dist - $ npm link - ``` +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. - These steps build core Blockly, package it, then create a symlink to the - packaged files. +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. -1. In your fork of blockly-samples, at root: - - ```shell - $ npm link blockly - ``` - - This step tells npm to look for the symlink you created earlier instead of - fetching the package from npm. - -1. `npm run start` from the plugin's directory to test your plugin. - -When you make changes in core, you'll have to rebuild and repackage it. - -When you're finished testing, run `npm ci` at the root level of blockly-samples -to reset the state of your repository. +:::tip +If you make additional changes to Blockly core, you'll need to repeat all of +these steps. +::: diff --git a/packages/docs/docs/guides/contribute/core/testing/playground.mdx b/packages/docs/docs/guides/contribute/core/testing/playground.mdx index 59ad02c87c9..0df7dbe80ca 100644 --- a/packages/docs/docs/guides/contribute/core/testing/playground.mdx +++ b/packages/docs/docs/guides/contribute/core/testing/playground.mdx @@ -79,7 +79,6 @@ This playground features all of the simple playground features plus: playground is loaded. - See the output of each generator in the same window. -TODO: double check, is this still how to start the advanced playground for a plugin? 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, diff --git a/packages/docs/docs/guides/programming/plugin_overview.mdx b/packages/docs/docs/guides/programming/plugin_overview.mdx index 0b308013ae4..290ef956ed4 100644 --- a/packages/docs/docs/guides/programming/plugin_overview.mdx +++ b/packages/docs/docs/guides/programming/plugin_overview.mdx @@ -192,6 +192,3 @@ This will let npm install any minor version at or above the listed version, so version `13.3.1` or `13.2.6` works, but a new major version such as `14.0.1` would not. When you update to a major version of Blockly, you should update your plugins as well. - -TODO: but would npm handle the plugin updates automatically if you bump the blockly -major version? how would that workflow look? From 6f4824a8ab7a45c2cf3e4c71a518b7fd21fb826b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zo=C3=AB=20Spriggs?= Date: Mon, 24 Aug 2026 14:02:52 -0600 Subject: [PATCH 5/7] docs: small cleanup and edit plugins doc --- .../contribute/core/plugins/add_a_plugin.mdx | 44 +++++++------------ .../guides/contribute/get-started/index.mdx | 16 ++++--- 2 files changed, 26 insertions(+), 34 deletions(-) diff --git a/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx b/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx index f2fd8a867f4..10f7c6e97b6 100644 --- a/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx +++ b/packages/docs/docs/guides/contribute/core/plugins/add_a_plugin.mdx @@ -56,13 +56,12 @@ First party plugins **must** meet these requirements: 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. -TODO +- Have tests. ## The process -Plugins go through four stages: [suggestion](#suggestion), -[discussion](#discussion), [implementation](#implementation), and +Plugins go through three stages: [suggestion](#suggestion), + [implementation](#implementation), and [publishing](#publishing). ## Suggestion @@ -82,37 +81,27 @@ include: - 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 agrees that it would be a good first-party plugin. - -## Discussion - -Next, a plugin goes into the **discussion** phase. This phase generally occurs -on the GitHub issue, and includes: - -- Clarification of the desired functionality and the plugin's API. -- Planning the implementation steps and tests. -- Discussion of API changes in core Blockly. -- Plugin naming, based on our [naming - conventions](/guides/contribute/samples/naming). -- Confirming all [first party criteria](#first-party-criteria) will be met. +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. -When discussion is complete a Blockly team member notes that it is ready to be -implemented. - ## 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 core logic for the plugin. -- Implementing a UI, if needed. +- Implementing the plugin. - Testing the plugin, using Mocha. - Documenting the plugin, including the `README`. @@ -120,9 +109,9 @@ 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 -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. +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 @@ -152,4 +141,5 @@ version numbers. Plugins that are not ready for publishing should be marked `private` in their `package.json`. -The Plugins site is also updated whenever plugins are published. +The [plugins site](https://raspberrypifoundation.github.io/blockly-samples/index.html) +will be updated whenever plugins are published. diff --git a/packages/docs/docs/guides/contribute/get-started/index.mdx b/packages/docs/docs/guides/contribute/get-started/index.mdx index d4c5c8215b0..d82d2c1f374 100644 --- a/packages/docs/docs/guides/contribute/get-started/index.mdx +++ b/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 examples that show uses of the Blockly -library. Use this repository if you want to create or modify 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 From 9c539be2977b098db3539184de4f5a45409eb855 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zo=C3=AB=20Spriggs?= Date: Mon, 24 Aug 2026 14:24:26 -0600 Subject: [PATCH 6/7] chore: fix phrasing --- .../docs/docs/guides/contribute/core/plugins/debugging.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx b/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx index 795088450dc..0b9ecf464ac 100644 --- a/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx +++ b/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx @@ -32,6 +32,6 @@ first build blockly. 1. Run `npm start` in the plugin's directory. :::tip -If you make additional changes to Blockly core, you'll need to repeat all of -these steps. +If you make additional changes to Blockly core, you'll need to redo steps 2, 3, +and 4. ::: From 91088c48876430190ed02649cd71499a9faa8065 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zo=C3=AB=20Spriggs?= Date: Mon, 24 Aug 2026 14:32:46 -0600 Subject: [PATCH 7/7] chore: format --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f037f24fbbd..0bf9cc09e0f 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ npm install blockly 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 +### 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/).