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..0bf9cc09e0f 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 new file mode 100644 index 00000000000..10f7c6e97b6 --- /dev/null +++ b/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. 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 95% 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..dd64c92d517 100644 --- a/packages/docs/docs/guides/contribute/samples/block_factory.mdx +++ b/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 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/core/plugins/debugging.mdx b/packages/docs/docs/guides/contribute/core/plugins/debugging.mdx new file mode 100644 index 00000000000..0b9ecf464ac --- /dev/null +++ b/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. +::: 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/core/testing/playground.mdx b/packages/docs/docs/guides/contribute/core/testing/playground.mdx index b404d575946..0df7dbe80ca 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,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. 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..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 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 diff --git a/packages/docs/docs/guides/contribute/samples.mdx b/packages/docs/docs/guides/contribute/samples.mdx new file mode 100644 index 00000000000..f289f7910b6 --- /dev/null +++ b/packages/docs/docs/guides/contribute/samples.mdx @@ -0,0 +1,92 @@ +--- +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.** 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. 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/add_a_plugin.mdx b/packages/docs/docs/guides/contribute/samples/add_a_plugin.mdx deleted file mode 100644 index d8def83c60e..00000000000 --- a/packages/docs/docs/guides/contribute/samples/add_a_plugin.mdx +++ /dev/null @@ -1,151 +0,0 @@ ---- -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 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 -`@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. - -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 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-samples. -- Have tests. - -## The process - -Plugins go through four stages: [suggestion](#suggestion), -[discussion](#discussion), [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-samples/issues/new?assignees=&labels=type%3A+feature+request%2C+triage&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 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 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](/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 -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 notes that it is ready to be -implemented. - -## Implementation - -**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-samples/tree/main/plugins/dev-create) -- Implementing core logic for the plugin. -- Implementing a UI, if needed. -- 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 -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.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. - -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](https://github.com/RaspberryPiFoundation/blockly). Core Blockly is published -in the last week of each quarter (once every three months). diff --git a/packages/docs/docs/guides/contribute/samples/debugging.mdx b/packages/docs/docs/guides/contribute/samples/debugging.mdx deleted file mode 100644 index fed54024271..00000000000 --- a/packages/docs/docs/guides/contribute/samples/debugging.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -description: How to test changes in blockly-samples that depend on changes in Blockly core. -title: Debug plugins -image: images/blockly_banner.png ---- - -# Debug plugins - -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. - -## npm link - -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. In your fork of blockly: - - ```shell - $ npm run package - $ cd dist - $ npm link - ``` - - These steps build core Blockly, package it, then create a symlink to the - packaged files. - -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. 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/docs/guides/contribute/samples/repository_structure.mdx b/packages/docs/docs/guides/contribute/samples/repository_structure.mdx deleted file mode 100644 index b6e990b3a6b..00000000000 --- a/packages/docs/docs/guides/contribute/samples/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/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 diff --git a/packages/docs/docs/guides/programming/plugin_overview.mdx b/packages/docs/docs/guides/programming/plugin_overview.mdx index 92ee2758b26..290ef956ed4 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,37 @@ 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. diff --git a/packages/docs/sidebars.js b/packages/docs/sidebars.js index b0681c7c980..9a04df12a34 100644 --- a/packages/docs/sidebars.js +++ b/packages/docs/sidebars.js @@ -1428,22 +1428,6 @@ 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', @@ -1451,32 +1435,37 @@ const sidebars = { { 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', + }, ], }, ],