diff --git a/packages/docs/docs/guides/contribute/core/add_localization_token.mdx b/packages/docs/docs/guides/contribute/core/add_localization_token.mdx deleted file mode 100644 index 9de4551e8a5..00000000000 --- a/packages/docs/docs/guides/contribute/core/add_localization_token.mdx +++ /dev/null @@ -1,135 +0,0 @@ ---- -description: How to add a new localization token to Blockly core. -title: Add a new localization token to Blockly core -image: images/blockly_banner.png ---- - -# Add a new localization token to Blockly core - -If you add a feature to Blockly core that requires new user-visible strings, you -must add those strings to `Blockly.Msg` so that they can be [translated by -Translatewiki][translatewiki]. (For information about adding localization tokens -for your own application, see [Localization][localization].) - -1. Add your new string with an appropriate name and description to the - `msg/messages.js` file. -1. Run `npm run messages` to automatically add your translation to the - `msg/json/qqq.json` and `msg/json/en.js` files. This step may also change - `msg/json/constants.js` or `msg/json/synonyms.js` in some cases. -1. Inspect the automatically-generated files for correctness. Note that the - script may remove the `@metadata` section at the beginning of `qqq.json`. If - this happens, you should carefully revert that change so that your new - string is added but the `@metadata` is not removed. -1. In your feature code, reference the new string with - `Blockly.Msg['MY_NEW_MESSAGE']`. -1. Commit all of the changes to the `msg` files alongside your feature code. - -For example, if you add this code to `msg/messages.js`: - -```js -/** @type {string} */ -/// This is a hint to translators about the context for the message. -Blockly.Msg.MY_NEW_MESSAGE = 'This is a string that users will see!'; -``` - -Then run `npm run messages`, you should see the following changes in -`msg/en.json`: - -```js -// ... - "MY_NEW_MESSAGE": "This is a message that users will see!", -// ... -``` - -and in `msg/qqq.json`: - -```js -// ... - "MY_NEW_MESSAGE": "This is a hint to translators about the context for the message.", -// ... -``` - -Then you can reference this string in code with `Blockly.Msg['MY_NEW_MESSAGE']`. - -## Translation hints - -The triple-slash comment in `msg/messages.js` is shown to TranslateWiki users as -supplementary information when translating. Provide context for where the -message will be shown to users. If the message includes parameters (e.g., `%1`), -explain what the parameters mean. - -Here is an example of a good translation hint that explains the parameters and -provides a link to more information. - -```js -/** @type {string} */ -/// block text - Repeatedly counts a variable (%1) -/// starting with a (usually lower) number in a range (%2), -/// ending with a (usually higher) number in a range (%3), and counting the -/// iterations by a number of steps (%4). As in -/// [https://github.com/RaspberryPiFoundation/blockly/wiki/Loops#count-with -/// https://github.com/RaspberryPiFoundation/blockly/wiki/Loops#count-with]. -Blockly.Msg.CONTROLS_FOR_TITLE = 'count with %1 from %2 to %3 by %4'; -``` - -### Context types - -Many of the hints use a prefix to explain the context of a message. The common -prefixes include: - -- block text -- button text -- context menu -- dropdown -- math -- toast notification -- tooltip - -If your message appears in one of these context, use the appropriate prefix. - -## Synonyms - -Sometimes a message key needs to be changed, but the translations don't. In that -case, you can set the old message as a synonym of the new message, like so: - -```js -/** @type {string} */ -Blockly.Msg.CONTROLS_FOR_INPUT_DO = Blockly.Msg.CONTROLS_REPEAT_INPUT_DO; -``` - -## Optional messages - -Some message strings are unlikely to need translation except in certain -circumstances, for example, proper nouns or symbols. In Blockly, help URLs are -often marked optional. - -Languages are only committed to the Blockly repository if they are at least 25% -complete. Thus, marking messages that are unlikely to need translating as -optional will help those languages meet the threshold without needing to -complete the optional translations. - -```js -/** @type {string} */ -/// {{Optional}} math - The symbol for the binary operation addition. -Blockly.Msg.MATH_ADDITION_SYMBOL = '+'; -``` - -## Notranslate items - -The colours used for default block categories are marked `{{notranslate}}`. These colours are not intended to be -localized, but are in the localization system so that developers can easily -[change the colours][block-colour] of blocks in the default categories. If you -add new block categories, use the `{{notranslate}}` -directive. If you add a different type of message that you think should never be -translated, consider whether the localization system is the right place for the -string. - -```js -/** @type {string} */ -/// {{Notranslate}} Hue value for all logic blocks. -Blockly.Msg.LOGIC_HUE = '210'; -``` - -[translatewiki]: /guides/contribute/core/translating -[localization]: /guides/configure/translations -[block-colour]: /guides/configure/appearance/block-colour#set-block-colour diff --git a/packages/docs/docs/guides/contribute/core/advanced.mdx b/packages/docs/docs/guides/contribute/core/building_and_compilation/advanced.mdx similarity index 100% rename from packages/docs/docs/guides/contribute/core/advanced.mdx rename to packages/docs/docs/guides/contribute/core/building_and_compilation/advanced.mdx diff --git a/packages/docs/docs/guides/contribute/core/building.mdx b/packages/docs/docs/guides/contribute/core/building_and_compilation/building.mdx similarity index 99% rename from packages/docs/docs/guides/contribute/core/building.mdx rename to packages/docs/docs/guides/contribute/core/building_and_compilation/building.mdx index ceda5223992..18190077bc6 100644 --- a/packages/docs/docs/guides/contribute/core/building.mdx +++ b/packages/docs/docs/guides/contribute/core/building_and_compilation/building.mdx @@ -8,7 +8,7 @@ image: images/blockly_banner.png :::warning Unless you are modifying the Blockly source code directly, you probably -don't need to build Blockly run any of the scripts documented below yourself. +don't need to build Blockly or run any of the scripts documented below yourself. Instead, follow the instructions in [the "Get the Code" section](/guides/get-started/get-the-code#get-the-code-1) of the [Get Started](/guides/get-started/get-the-code) page to install [the `blockly` NPM package](https://www.npmjs.com/package/blockly) or download the `.tgz` file attached to [the latest release on GitHub](https://github.com/RaspberryPiFoundation/blockly/releases/latest). diff --git a/packages/docs/docs/guides/contribute/core/core-architecture/core-tour.mdx b/packages/docs/docs/guides/contribute/core/core-architecture/core-tour.mdx new file mode 100644 index 00000000000..f17d0948acf --- /dev/null +++ b/packages/docs/docs/guides/contribute/core/core-architecture/core-tour.mdx @@ -0,0 +1,159 @@ +--- +description: Overview of the structure and architecture of the core repository. +title: Core Tour +image: images/blockly_banner.png +--- + +# Core tour + +## Blockly code + +The code for Blockly can be found on +[GitHub](https://github.com/RaspberryPiFoundation/blockly/tree/main). This +page is intended as a guide so that you can explore Blockly's repository and +determine where to start if you're working on a GitHub issue. + +If you would like to learn more about Blockly's code, you can do the following: +- Read this document +- Click through the code on [GitHub](https://github.com/RaspberryPiFoundation/blockly/tree/main) +- Consult the [API documentation](/reference/blockly/) + +:::tip +Don't worry, you do **not** have to read and understand every piece of Blockly's +code in order to contribute to Blockly! You just need to understand the parts +that relate to what you're working on. +::: + +### Folder structure + +The root folder of Blockly's repository contains many files (and some folders) +for the configuration of our +[development tools](/guides/contribute/core/development_tools). + +Blockly's source code is located in `packages/blockly`. As an external +contributor, you will likely focus on the files in the `core/` and `tests/` +folders, but all of the folders are listed below. + +`packages/blockly/` +- `blocks/` - Block definitions for built-in blocks +- `core/` + - `bubbles/` - Code for creating popover bubbles, such as mutator UI + - `clipboard/` - [Copy/paste](/guides/configure/copy-paste/) logic + - `comments/` - Workspace [comments](/guides/configure/) + - `dragging/` - Mechanics for + [dragging objects](/guides/configure/dragging/draggable/) in the workspace + - `events/` - [Events](/guides/configure/events) class and built-in events + - `icons/` - [Icon](/guides/create-custom-blocks/icons/overview/) class and + built-in icons + - `inputs/` - + [Input](/guides/create-custom-blocks/inputs/creating-custom-inputs/) types + and their connections + - `interfaces/` - Shared interfaces implemented across core + - `keyboard_nav/` - [Keyboard navigation](/guides/configure/keyboard-nav/) + - `navigation_policies/` - Engines that decide where keyboard focus moves + - `navigators/` - Per-element rules telling the navigator where an element's + neighbors are + - `renderers/` - Default + [renderers](/guides/create-custom-blocks/renderers/overview/) + - `common/` - Base classes shared by the renderers + - `geras/` - Built-in renderer with 3-D edges + - `measurables/` - Classes that represent each part of a block + - `thrasos/` - Built-in minimalist renderer, Blockly default + - `zelos/` - Built-in renderer with rounded blocks + - `serialization/` - [Saving and loading](/guides/configure/serialization/) + workspace state + - `theme/` - Built-in [themes](/guides/configure/appearance/themes/) + - `toolbox/` - The [toolbox](/guides/configure/toolboxes/toolbox/) and flyout + - `utils/` - Utility functions used throughout core +- `demos/` - Some Blockly demos. Most demos and examples are in [blockly-samples](https://github.com/raspberrypifoundation/blockly-samples). +- `generators/` - + [Code generators](/guides/create-custom-blocks/code-generation/overview/) for + the built-in languages +- `media/` - Sound effects, cursors, etc. +- `msg/` - Translated [message strings](/guides/configure/translations/) +- `scripts/` - Scripts for building, packaging, and maintaining Blockly. +- `tests/` - [Unit tests](/guides/contribute/core/testing/unit_testing) +- `typings/` - Supplemental hand-written type declarations + +### Core files + +There are many files in `core/` that don't live in a subfolder, for various +reasons. If you're making a change to Blockly, you should take a look at these +files, as well as the subfolders in `core/`, to find the relevant code. + +Note that Blockly's foundational base classes, like `Block`, `Workspace`, and +`Connection` are located in the `core/` folder, outside of any subcategories. + +## Blockly docs + +Blockly's documentation is located in `packages/docs`. + +As an external contributor, you will likely focus on the files in the `docs/` +and `static/` folders, but all of the folders are listed below. + +`packages/docs/` +- `docs/` - The documentation content itself, written in Markdown/MDX + - `codelabs/` - Step-by-step tutorials + - `guides/` - Topic-based how-to guides + - `publications/` - Academic papers and talks about Blockly + - `reference/` - Generated [API reference](#api-documentation) +- `src/` - Source code for the Docusaurus site + - `components/` - Custom React components used in the docs + - `css/` - Custom styles + - `pages/` - Standalone pages outside the docs content + - `theme/` - Docusaurus theme overrides + - `utils/` - Utilities for website analytics +- `static/` - Static assets (images, redirects, etc.) + +### API documentation + +Blockly also offers [API reference documentation](/reference/blockly) that +details the public API code. The API docs are automatically generated from the +code itself, so they are another great resource for understanding Blockly's +code. + +## Model vs. view + +Before digging into `core/`, it's worth understanding one key part of Blockly's +architecture: Blockly separates data modeling from rendering. In practice, this +means that many parts of Blockly have two classes that represent them: one for +the data model, and one for the rendered version. + +For an example, look at the implementation of blocks. In the `core/` folder, +there are two files that implement blocks: `block.ts` and `block_svg.ts`. + +In `block.ts`, the `Block` parent class has functions to handle data associated +with that block and how it behaves. There are functions in the `Block` class +that do deal with visual aspects of a block, like `setColour`. If you look +closely at `setColour` in the `Block` class, you'll see that `setColour` just +saves the colour. It does not render or display that colour. + +`block_svg.ts`, on the other hand, creates a `BlockSvg` class that extends the +`Block` class to add render management. The `setColour` override in BlockSvg +calls the super (which saves the colour) and also *applies* that colour +to the rendered block. + +### Headless workspaces + +The model/view architecture makes it possible for Blockly to run headless. This +means that the data models that represent Blockly components can run without rendering anything in a +browser. Running Blockly in headless mode can be useful for testing, server-side +operations, or executing operations without rendering more workspaces (see the +[parallel program example](/guides/design/applications#parallel-program)). + +To create a headless workspace, you can use `new Blockly.Workspace()` instead of +injecting Blockly. + +```js +const renderedWorkspace = Blockly.inject(blocklyDiv); +const headlessWorkspace = new Blockly.Workspace(); +``` + +### Conventions + +When you see a class named `…Svg` (`BlockSvg`, `WorkspaceSvg`) or `Rendered…` +(`RenderedConnection`), that's the "view" half of a model/view pair. + +Note that some smaller components, like `Field`, do combine both the model and +view into one file. Where the model and view are combined, there is still a +`rendered` flag that determines whether the component will actually be rendered. diff --git a/packages/docs/docs/guides/contribute/core-architecture/render-management.mdx b/packages/docs/docs/guides/contribute/core/core-architecture/render-management.mdx similarity index 100% rename from packages/docs/docs/guides/contribute/core-architecture/render-management.mdx rename to packages/docs/docs/guides/contribute/core/core-architecture/render-management.mdx diff --git a/packages/docs/docs/guides/contribute/get-started/development_tools.mdx b/packages/docs/docs/guides/contribute/core/development_tools.mdx similarity index 84% rename from packages/docs/docs/guides/contribute/get-started/development_tools.mdx rename to packages/docs/docs/guides/contribute/core/development_tools.mdx index 969cc18052a..42e775aefd2 100644 --- a/packages/docs/docs/guides/contribute/get-started/development_tools.mdx +++ b/packages/docs/docs/guides/contribute/core/development_tools.mdx @@ -14,22 +14,6 @@ We use many of these tools through scripts. You may not need to ever run them directly. Knowing the names may still be helpful for debugging or filing issues or feature requests. -### Git - -[Git](https://git-scm.com/) is a version control system that we use to track and -manage changes to files. - -### GitHub - -[GitHub](https://github.com/) is a hosting platform for version control, -collaboration, and distribution of open-source code. Git tracks the files; -GitHub provides smooth interfaces for reviewing code, tracking issues, and -viewing change history. - -**Getting started**: If you're new to Git and GitHub, work through GitHub's -[quickstart](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/quickstart) -tutorials to get comfortable with the basics. - ### Node [Node.js](https://nodejs.org/) is a way to run JavaScript on the server (rather diff --git a/packages/docs/docs/guides/contribute/core/index.mdx b/packages/docs/docs/guides/contribute/core/index.mdx index e341caec76b..b3a193acd48 100644 --- a/packages/docs/docs/guides/contribute/core/index.mdx +++ b/packages/docs/docs/guides/contribute/core/index.mdx @@ -17,8 +17,8 @@ to create a PR. - The working branch is **main** and all PRs should be made against main. - You must fill out the pull request template with the requested information. -- Code must conform to Google's [TypeScript Style - Guide](https://google.github.io/styleguide/tsguide.html). +- Code must conform to Blockly's [style guide](style_guide), which is the same +as Google's [TypeScript style guide](https://google.github.io/styleguide/tsguide.html). - Use [conventional commits](/guides/contribute/get-started/commits) in your commit messages and pull request titles. - User-visible strings must be in the `/msg/messages.js` file so they may be diff --git a/packages/docs/docs/guides/contribute/core/klingon.mdx b/packages/docs/docs/guides/contribute/core/klingon.mdx deleted file mode 100644 index 7fe77aa64e2..00000000000 --- a/packages/docs/docs/guides/contribute/core/klingon.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Klingon -image: images/blockly_banner.png ---- - -# Klingon - -On 1 April 2014 we released a -[Klingon translation of Blockly](https://blockly-demo.appspot.com/static/demos/code/index.html?lang=tlh#ortpyd). -Klingon is an unusual choice for a translation, and on this page we wanted to -give some context on the hows and whys, as well as how you can help. - -![A stack of blocks in Klingon.](/images/klingon.png) - -## Why? - -Blockly has been translated into over 40 languages, including RTL languages such -as Arabic and Hebrew. We feel that it is important that novice programmers are -able to learn the fundamentals of programming in their own language, before -making the transition to conventional English-based programming languages. - -Klingon is a real language in every sense of the word. It is not just a -collection of made-up words thrown together for a movie. Instead, it has been -crafted by linguists over the course of decades. The Klingon language has a -complicated grammar that is completely unique. - -Consider word order. English follows the Subject-Verb-Object order ("The cat -eats the food."). Hungarian follows the Object-Subject-Verb order ("The food -the cat eats."). Hebrew follows the Verb-Subject-Object order ("Eats the cat -the food."). Klingon is the most bizarre, with Object-Verb-Subject order ("The -food eats the cat."). Supporting Klingon is the ultimate test of Blockly's -flexibility. Block inputs need to be reordered, suffix groups need to be added, -rules for plurals need to be rethought. Infrastructure improvements made during -the course of translating to Klingon help us support all languages. - -## Who? - -The number of Google employees who are fluent in Klingon is larger than one -might expect. Google's Klingon language group maintains -a style guide for terminology so that different applications use a consistent -vocabulary. - -We are always pleased when volunteers come forward to contribute new -translations or corrections -- whether for Klingon, or other languages. - -## How? - -Most of [Blockly's translations](/guides/contribute/core/translating) are done by volunteers -using Translatewiki. Unfortunately, Klingon is not in their language matrix. -As a result, Klingon contributors need to edit two files manually: - -[msg/json/tlh.json](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/blockly/msg/json/tlh.json) -and -[demos/code/msg/tlh.js](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/blockly/demos/code/msg/tlh.js) - -See the `en` files in each directory for the English phrases (including -those not yet translated to Klingon). -We actively do not want tooltip messages or help URLs translated since they -offer useful context for those new to Klingon. - -All phrases _must_ be manually translated. Bing Translate produces such -translations as `"Library" -> "be'nI''a'wI', Datu'"` which actually means -`"discover my big sister"`. -Clearly this would be an inadvisable phrase to use in a Klingon environment. diff --git a/packages/docs/docs/guides/contribute/core/localization_and_translation.mdx b/packages/docs/docs/guides/contribute/core/localization_and_translation.mdx new file mode 100644 index 00000000000..dff26f8121b --- /dev/null +++ b/packages/docs/docs/guides/contribute/core/localization_and_translation.mdx @@ -0,0 +1,221 @@ +--- +description: How to add a new localization token to Blockly core. +title: Add a new localization token to Blockly core +image: images/blockly_banner.png +--- +# Localization and translation + +Blockly uses a localization system to translate user-visible text into a variety +of languages. If you add a feature to Blockly core that requires new +user-visible strings, you must add those strings to the message file so that +they can be [translated by Translatewiki](#translatewiki). For information about +adding localization tokens for your _own_ application, see +[Localization][localization]. + +## Add a new localization token to Blockly core + +New user-visible strings must be added to `Blockly.Msg`. Follow +these steps to ensure that the new strings can be properly translated: + +1. Add your new string with an appropriate name and description to the + `msg/messages.js` file. +1. Run `npm run messages` to automatically add your translation to the + `msg/json/qqq.json` and `msg/json/en.js` files. This step may also change + `msg/json/constants.js` or `msg/json/synonyms.js` in some cases. +1. Inspect the automatically-generated files for correctness. Note that the + script may remove the `@metadata` section at the beginning of `qqq.json`. If + this happens, you should carefully revert that change so that your new + string is added but the `@metadata` is not removed. +1. In your feature code, reference the new string with + `Blockly.Msg['MY_NEW_MESSAGE']`. +1. Commit all of the changes to the `msg` files alongside your feature code. + +For example, if you add this code to `msg/messages.js`: + +```js +/** @type {string} */ +/// This is a hint to translators about the context for the message. +Blockly.Msg.MY_NEW_MESSAGE = 'This is a string that users will see!'; +``` + +Then run `npm run messages`, you should see the following changes in +`msg/en.json`: + +```js +// ... + "MY_NEW_MESSAGE": "This is a message that users will see!", +// ... +``` + +and in `msg/qqq.json`: + +```js +// ... + "MY_NEW_MESSAGE": "This is a hint to translators about the context for the message.", +// ... +``` + +Then you can reference this string in code with `Blockly.Msg['MY_NEW_MESSAGE']`. + +### Translation hints + +The triple-slash comment in `msg/messages.js` is shown to TranslateWiki users as +supplementary information when translating. Provide context for where the +message will be shown to users. If the message includes parameters (e.g., `%1`), +explain what the parameters mean. + +Here is an example of a good translation hint that explains the parameters and +provides a link to more information. + +```js +/** @type {string} */ +/// block text - Repeatedly counts a variable (%1) +/// starting with a (usually lower) number in a range (%2), +/// ending with a (usually higher) number in a range (%3), and counting the +/// iterations by a number of steps (%4). As in +/// [https://github.com/RaspberryPiFoundation/blockly/wiki/Loops#count-with +/// https://github.com/RaspberryPiFoundation/blockly/wiki/Loops#count-with]. +Blockly.Msg.CONTROLS_FOR_TITLE = 'count with %1 from %2 to %3 by %4'; +``` + +#### Context types + +Many of the hints use a prefix to explain the context of a message. The common +prefixes include: + +- block text +- button text +- context menu +- dropdown +- math +- toast notification +- tooltip + +If your message appears in one of these context, use the appropriate prefix. + +### Synonyms + +Sometimes a message key needs to be changed, but the translations don't. In that +case, you can set the old message as a synonym of the new message, like so: + +```js +/** @type {string} */ +Blockly.Msg.CONTROLS_FOR_INPUT_DO = Blockly.Msg.CONTROLS_REPEAT_INPUT_DO; +``` + +### Optional messages + +Some message strings are unlikely to need translation except in certain +circumstances, for example, proper nouns or symbols. In Blockly, help URLs are +often marked optional. + +Languages are only committed to the Blockly repository if they are at least 25% +complete. Thus, marking messages that are unlikely to need translating as +optional will help those languages meet the threshold without needing to +complete the optional translations. + +```js +/** @type {string} */ +/// {{Optional}} math - The symbol for the binary operation addition. +Blockly.Msg.MATH_ADDITION_SYMBOL = '+'; +``` + +### Notranslate items + +The colours used for default block categories are marked `{{notranslate}}`. These colours are not intended to be +localized, but are in the localization system so that developers can easily +[change the colours][block-colour] of blocks in the default categories. If you +add new block categories, use the `{{notranslate}}` +directive. If you add a different type of message that you think should never be +translated, consider whether the localization system is the right place for the +string. + +```js +/** @type {string} */ +/// {{Notranslate}} Hue value for all logic blocks. +Blockly.Msg.LOGIC_HUE = '210'; +``` + +[translatewiki]: /guides/contribute/core/translating +[localization]: /guides/configure/translations +[block-colour]: /guides/configure/appearance/block-colour#set-block-colour + +# Translate text + +Students shouldn't have to struggle with learning English at the same time as +they're learning computer science concepts. If you are a native speaker of a +language other than English, we'd appreciate your assistance in reaching the 95% +of the world that doesn't speak English natively. + +## Translatewiki + +Translations for Blockly are handled by Translatewiki. + +1. Sign up to become a translator at + [translatewiki.net](https://translatewiki.net/). +1. Do some [test + translations](https://translatewiki.net/wiki/Special:TranslationStash) to + get permission to translate (choose a language in the upper-right). +1. Briefly read over the [style + guide](https://translatewiki.net/wiki/Translating:Blockly) for Blockly's + translations. +1. Go to Blockly's [message group](https://translatewiki.net/w/i.php?title=Special:Translate&group=out-blockly-0-all) + (choose a language in the upper-right), and start translating! + +New translations may take a few months to show up on the live site. + +![A photo showing three Vietnamese girls in front of a +computer.](/images/vietnam.jpg) + +Note that [Klingon](klingon) is not supported by Translatewiki, so that language +needs to be handled separately. + +## Klingon translations + +On 1 April 2014 we released a +[Klingon translation of Blockly](https://blockly-demo.appspot.com/static/demos/code/index.html?lang=tlh#ortpyd). +Klingon is an unusual choice for a translation, and on this page we wanted to +give some context on the hows and whys, as well as how you can help. + +![A stack of blocks in Klingon.](/images/klingon.png) + +### Why? + +Blockly has been translated into over 40 languages, including RTL languages such +as Arabic and Hebrew. We feel that it is important that novice programmers are +able to learn the fundamentals of programming in their own language, before +making the transition to conventional English-based programming languages. + +Klingon is a real language in every sense of the word. It is not just a +collection of made-up words thrown together for a movie. Instead, it has been +crafted by linguists over the course of decades. The Klingon language has a +complicated grammar that is completely unique. + +Consider word order. English follows the Subject-Verb-Object order ("The cat +eats the food."). Hungarian follows the Object-Subject-Verb order ("The food +the cat eats."). Hebrew follows the Verb-Subject-Object order ("Eats the cat +the food."). Klingon is the most bizarre, with Object-Verb-Subject order ("The +food eats the cat."). Supporting Klingon is the ultimate test of Blockly's +flexibility. Block inputs need to be reordered, suffix groups need to be added, +rules for plurals need to be rethought. Infrastructure improvements made during +the course of translating to Klingon help us support all languages. + +### How? + +Most of [Blockly's translations](/guides/contribute/core/translating) are done by volunteers +using Translatewiki. Unfortunately, Klingon is not in their language matrix. +As a result, Klingon contributors need to edit two files manually: + +[msg/json/tlh.json](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/blockly/msg/json/tlh.json) +and +[demos/code/msg/tlh.js](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/blockly/demos/code/msg/tlh.js) + +See the `en` files in each directory for the English phrases (including +those not yet translated to Klingon). +We actively do not want tooltip messages or help URLs translated since they +offer useful context for those new to Klingon. + +All phrases _must_ be manually translated. Bing Translate produces such +translations as `"Library" -> "be'nI''a'wI', Datu'"` which actually means +`"discover my big sister"`. +Clearly this would be an inadvisable phrase to use in a Klingon environment. diff --git a/packages/docs/docs/guides/contribute/core/style_guide.mdx b/packages/docs/docs/guides/contribute/core/style_guide.mdx index 0ceb68161be..3f9a481c5f4 100644 --- a/packages/docs/docs/guides/contribute/core/style_guide.mdx +++ b/packages/docs/docs/guides/contribute/core/style_guide.mdx @@ -14,7 +14,7 @@ guide](https://google.github.io/styleguide/tsguide.html). Blockly was originally written in ES5.1 in compliance with an [older, then-current version of the Google JavaScript style guide](https://google.github.io/styleguide/javascriptguide.xml). Newly-written -code should comply with the current style guide and use ES6 language features +code should comply with the [current style guide](https://google.github.io/styleguide/tsguide.html) and use ES6 language features like `let`, `const`, `class`, destructuring assignment where applicable. Existing code may be updated or may be left out of compliance. The Blockly team tries to make the best decision taking into account code consistency and the @@ -25,18 +25,17 @@ public functions that no longer comply with the style guide. - Use linting and formatting tools. - We use [eslint](http://eslint.org/) and have an [`eslint.config.mjs` - file](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/blockly/eslint.config.mjs) + file](https://github.com/RaspberryPiFoundation/blockly/blob/main/eslint.config.mjs) set up with rules for our preferred style. - We use [prettier](https://prettier.io/) for automatic formatting. - Run `npm run lint` to run the linter and `npm run format` to run the formatter. - Indent with spaces, not tabs. -- Use [semicolons][semicolons-rule]. +- Use [semicolons](https://google.github.io/styleguide/tsguide.html#automatic-semicolon-insertion). - Use `camelCase` for variables and functions. - Use `TitleCase` for classes. - Use `ALL_CAPS` for constants. -- [Use braces](https://google.github.io/styleguide/jsguide.html#formatting-braces-all) - for all control structures. +- Use braces for all control structures. - Exception: You may omit the braces for single-line `if` statements. - Use single quotes (except when writing JSON). - Redeclare variables in `for` loops. That is, always write `for (const i = 0; @@ -130,5 +129,3 @@ export function getWorkspaceById(id: string): Workspace | null { return WorkspaceDB_[id] || null; } ``` - -[semicolons-rule]: https://google.github.io/styleguide/jsguide.html#formatting-semicolons-are-required diff --git a/packages/docs/docs/guides/contribute/get-started/playground.mdx b/packages/docs/docs/guides/contribute/core/testing/playground.mdx similarity index 100% rename from packages/docs/docs/guides/contribute/get-started/playground.mdx rename to packages/docs/docs/guides/contribute/core/testing/playground.mdx diff --git a/packages/docs/docs/guides/contribute/core/unit_testing.mdx b/packages/docs/docs/guides/contribute/core/testing/unit_testing.mdx similarity index 100% rename from packages/docs/docs/guides/contribute/core/unit_testing.mdx rename to packages/docs/docs/guides/contribute/core/testing/unit_testing.mdx diff --git a/packages/docs/docs/guides/contribute/core/translating.mdx b/packages/docs/docs/guides/contribute/core/translating.mdx deleted file mode 100644 index c3030f8ab3e..00000000000 --- a/packages/docs/docs/guides/contribute/core/translating.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -description: How to contribute translations to Blockly. -title: Translate text -image: images/blockly_banner.png ---- - -# Translate text - -Students shouldn't have to struggle with learning English at the same time as -they're learning computer science concepts. If you are a native speaker of a -language other than English, we'd appreciate your assistance in reaching the 95% -of the world that doesn't speak English natively. - -## Translatewiki - -Translations for both Blockly and Blockly Games are handled by Translatewiki. - -1. Sign up to become a translator at - [translatewiki.net](https://translatewiki.net/). -1. Do some [test - translations](https://translatewiki.net/wiki/Special:TranslationStash) to - get permission to translate (choose a language in the upper-right). -1. Briefly read over the [style - guide](https://translatewiki.net/wiki/Translating:Blockly) for Blockly's - translations. -1. Go to Blockly's [message group](https://translatewiki.net/w/i.php?title=Special:Translate&group=out-blockly-0-all) - (choose a language in the upper-right), and start translating! - -New translations may take a few months to show up on the live site. - -![A photo showing three Vietnamese girls in front of a -computer.](/images/vietnam.jpg) - -Note that [Klingon](klingon) is not supported by Translatewiki, so that language -needs to be handled separately. diff --git a/packages/docs/docs/guides/contribute/core/write_a_codelab.mdx b/packages/docs/docs/guides/contribute/core/write_a_codelab.mdx index 8ff5e6b987e..8aab0b4fa98 100644 --- a/packages/docs/docs/guides/contribute/core/write_a_codelab.mdx +++ b/packages/docs/docs/guides/contribute/core/write_a_codelab.mdx @@ -29,13 +29,13 @@ understanding code to complete a specific task. ### Process If you have an idea for a codelab, you can tell us about it by making a -[feature request](/guides/contribute/get-started/write_a_good_issue#feature-request) +[feature request](/guides/contribute/get-started/write_a_good_issue#feature-requests) in the blockly repository. Include a description of what you want to teach and what you will build in the codelab. We'll discuss and refine the idea. Then you can write it up and [submit a pull request](/guides/contribute/get-started/write_a_good_pr) for it. Once it's been through -[review](/guides/contribute/get-started/pr_review_process), a member of the +[review](/guides/contribute/get-started/write_a_good_pr#read-the-review), a member of the Blockly team will publish it. ## Directory structure diff --git a/packages/docs/docs/guides/contribute/get-started/commits.mdx b/packages/docs/docs/guides/contribute/get-started/commits.mdx index 91d945412c1..c1080c566f9 100644 --- a/packages/docs/docs/guides/contribute/get-started/commits.mdx +++ b/packages/docs/docs/guides/contribute/get-started/commits.mdx @@ -9,7 +9,7 @@ image: images/blockly_banner.png ## Commit messages Clear commit messages make pull requests easier to review, and release notes -easier to generate. The Blockly project uses +easier to generate. Blockly uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) to help with this. @@ -23,7 +23,7 @@ Each commit should have the format: [optional footer(s)] ``` -Note that the core Blockly repo has a commit linter to help enforce this. If +Note that the Blockly repo has a commit linter to help enforce this. If your pull request has multiple commits, the linter will check the title. If it has a single commit, it will check that commit. It is best if both your individual commits and the pull request title follow these guidelines. @@ -42,7 +42,7 @@ accepted types. - **`fix`:** For commits that fix bugs/errors in Blockly. -- **`docs`:** For commits that update or add documentation. +- **`docs`:** For commits that update or add documentation only. - **`release`:** For commits that relate to the release of a new version. @@ -64,19 +64,13 @@ Breaking changes could have any of the above valid types. The description must be non-empty, and must be under 256 characters. -### Body +### Body & Footer -The body is optional. If it is provided there should be a blank line between it -and the description. It must be broken into lines of no more than 256 -characters. +The body and footer are optional. If provided, there should be blank lines +between the description, body, and footer. -Note that usually, it is advisable to put this kind of information in your -pull request description, in addition to/rather than directly in the commit. - -### Footer - -The footer is optional. If it is provided there should be a blank line between -it and the body. It must be broken into lines of no more than 256 characters. +Note that usually, it is advisable to put additional information in your +pull request description rather than directly in the commit. ## Fixing non-conventional commits diff --git a/packages/docs/docs/guides/contribute/get-started/index.mdx b/packages/docs/docs/guides/contribute/get-started/index.mdx index 9e261c254e5..012909479d2 100644 --- a/packages/docs/docs/guides/contribute/get-started/index.mdx +++ b/packages/docs/docs/guides/contribute/get-started/index.mdx @@ -9,8 +9,12 @@ image: images/blockly_banner.png Blockly is open source and is primarily maintained by a small team. We welcome contributions from developers outside the core team; there is no way for us to build every requested feature or fix every reported bug without our community. -This section contains general guides that may be helpful to you especially if -you are new to open source development. + +:::info +This section contains general guides on contributing to Blockly. These guides +are generally intended for those who are new to Blockly or new to open-source +development. +::: For information specific to Blockly that you should read before making a contribution, see the @@ -30,34 +34,49 @@ 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. -## Step by step +### Pre work: Understand Git and GitHub basics -These are the general steps you will follow any time you make a change. +We use Git and GitHub for managing version control, collaboration, and distribution +of Blockly. If you're new to Git and GitHub, work through GitHub's +[quickstart](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/quickstart) +tutorials to get comfortable with the basics. + +To learn about the rest of Blockly's development tools, see the [Contribute to Core](/guides/contribute/core/) +documentation. + +### Setup + +These are the one-time setup steps you'll need to get started: -1. **Install** Git and Node, following the links in the [Tools](/guides/contribute/get-started/development_tools) - section. +1. **Install** [Git](https://github.com/git-guides/install-git) and [Node](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) 1. **Fork and clone the repository.** GitHub has a wonderful tutorial about [forking a repo](https://help.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository). To apply it to blockly, just replace every instance of **octocat/Spoon-Knife** with **RaspberryPiFoundation/blockly** or **RaspberryPiFoundation/blockly-samples**, depending on which repository you want to work in. + +### Step by step + +These are the general steps you will follow any time you make a change. + 1. **Sync your fork.** GitHub provides a tutorial for - [syncing a fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork) - as well. -1. **Check out the main branch.** In blockly core and blockly-samples, this branch is named `main`. + [syncing a fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork). +1. **Check out the `main` branch** by running `git checkout main` in a + terminal. 1. **Install** dependencies and build tools by running `npm install` in the root directory. 1. **Create a new branch** by running `git checkout -b myBranchName` in a - terminal. The name should help you remember what you're working on. + terminal. The branch name should help you remember what you're working on. 1. **Make your changes.** 1. **Validate your changes,** following the guide for [core](/guides/contribute/core) or [samples](/guides/contribute/samples). -1. **Save your changes** with `git commit -am "fix: My commit message"`. - [Read more about commit messages](#). +1. **Add your changes** to a commit with `git add your/file/path`. +1. **Save your changes** with `git commit -m "fix: My commit message"`. + [Read more about commit messages](commits). 1. **Push your changes** to GitHub with `git push origin myBranchName`. 1. **Open a pull request** when your code is ready. A member of the Blockly team will review your changes and merge them into Blockly if they are approved. For more information see - [PR Review Process](/guides/contribute/get-started/pr_review_process). + [PR Review Process](/guides/contribute/get-started/write_a_good_pr#read-the-review). diff --git a/packages/docs/docs/guides/contribute/get-started/issue_labels.mdx b/packages/docs/docs/guides/contribute/get-started/issue_labels.mdx deleted file mode 100644 index a1e68effdab..00000000000 --- a/packages/docs/docs/guides/contribute/get-started/issue_labels.mdx +++ /dev/null @@ -1,148 +0,0 @@ ---- -description: Issue labels used in blocky and blockly-samples. -title: Issue labels -image: images/blockly_banner.png ---- - -# Issue labels - -Labels are a cool feature of GitHub that allow you to filter issues and pull -requests. They help you find something fun to work on that fits with your level -of experience. - -For our repositories, adding new labels to issues is handled exclusively by the -core Blockly team, to make sure that things don't end up in the wrong spot. - -:::note -For more information about using labels, see -[Filtering issues and pull requests](https://help.github.com/en/github/managing-your-work-on-github/filtering-issues-and-pull-requests-by-labels). -::: - -### Size - -Some issues are bite-sized and beautiful, while others could take weeks to -defeat. These labels help you tell how much work an issue will probably take. - -- **[Good first issue](https://github.com/RaspberryPiFoundation/blockly-samples/labels/good%20first%20issue):** - These issues are great for people who are new to the repository. They should - take less than half a day's work and require limited familiarity with the - code base. You can start work on these issues immediately, without approval - from the team. - -### Jurisdiction - -Working on a widely-used repo can be a sensitive process, and some issues can be -more sensitive than others. These labels help you tell which issues are open for -contribution, and which issues to steer clear of. - -- **[Help wanted](https://github.com/RaspberryPiFoundation/blockly-samples/labels/help%20wanted):** - These issues are reserved for contributors. Often they are features the core - team think would be useful, but don't have time to implement. They may need - either discussion or implementation, so check the status label to see what - work is needed. This is a good place to find fun creative projects! -- **[Internal](https://github.com/RaspberryPiFoundation/blockly-samples/labels/internal):** - These issues are reserved for members of the core team. Often they are - sensitive or complex bugs that need special discussion. It's best to steer - clear of these because the situation around them could change rapidly! -- **[Neither](https://github.com/RaspberryPiFoundation/blockly-samples/issues?q=is%3Aissue+is%3Aopen+-label%3A%22help+wanted%22+-label%3A%22internal%22):** - Issues that have neither label can be fixed by contributors _and_ members of - the core team. If you see an unlabeled issue that seems interesting to you, - go ahead and take it! - -### Status - -Certain issues (particularly feature requests) go through a few different stages -before they can be considered "closed". These labels tell you what stage an -issue is currently in, so you can know what needs to be done next. - -- **[Discussion](https://github.com/RaspberryPiFoundation/blockly-samples/labels/status%3A%20discussion):** - These issues are in the - [discussion phase](/guides/contribute/samples/add_a_plugin#discussion), - which means there are still questions that need to be answered before - implementation. If you have any thoughts related to this issue, feel free to - leave a comment! We're always looking for more input. -- **[Implementation](https://github.com/RaspberryPiFoundation/blockly-samples/labels/status%3A%20implementation):** - These issues have had enough discussion that they are clearly defined, and - have moved into the [implementation phase](/guides/contribute/samples/add_a_plugin#implementation). - They are either waiting for implementation, or already being implemented. If - you're interested in working on one of these, read through the whole issue - and then leave a comment saying which part you want to work on, then go - ahead and dive in! -- **[Neither](https://github.com/RaspberryPiFoundation/blockly-samples/issues?q=is%3Aissue+is%3Aopen+-label%3A%22status%3A+discussion%22+-label%3A%22status%3A+implementation%22+):** - Issues that have neither label could be in either state. If you have an - opinion about how the issue should be implemented, go ahead and leave a - comment! Alternatively if you're interested in _working_ on the issue, it is - best to leave a comment asking if it is ready to be implemented. - -### Type - -Different issues require different responses. Some only require editing a few -lines of code, while others need lots of design and discussion. These labels -tell you what type of action an issue will need. - -- **[Bug](https://github.com/RaspberryPiFoundation/blockly-samples/labels/type%3A%20bug):** - These issues document a problem with the codebase. They often take some - debugging to diagnose what's causing the problem, but some can be fixed in a - wink. If you like digging deep to learn how the code ticks, these will be - great issues for you. You can help either by fixing the bug or by digging to - understand the issue and writing a clear explanation of the root cause. -- **[Feature request](https://github.com/RaspberryPiFoundation/blockly-samples/labels/type%3A%20feature%20request):** - These issues document a feature that someone would like to have added. This - can apply to the repository as a whole, or to an individual project. If you - like fleshing out design ideas and adding new functionality, these could be - the perfect issues for you. -- **[Question](https://github.com/RaspberryPiFoundation/blockly-samples/labels/type%3A%20question):** - These issues document a question someone has about the codebase. Generally - these questions are redirected to the - [developer forum](https://groups.google.com/g/blockly), but if - you see a question you feel you could help with, feel free to jump in and - respond. - -### Category - -This repository contains a few different kinds of projects, with a few different -kinds of target audiences. If you are passionate about tutorials, or love -working on plugins, these labels can help you find issues you're interested in. - -- **[Codelab](https://github.com/RaspberryPiFoundation/blockly/labels/category%3A%20codelab):** - These issues relate to Blockly - [codelabs](/guides/contribute/core/write_a_codelab/), - a suite of interactive tutorials. -- **[Example](https://github.com/RaspberryPiFoundation/blockly-samples/labels/category%3A%20example):** - These issues relate to Blockly - [examples](/guides/contribute/samples/repository_structure#examples), - a set of self-contained demos showcasing how to include and extend Blockly. -- **[Plugin](https://github.com/RaspberryPiFoundation/blockly-samples/labels/category%3A%20plugin):** - These issues relate to Blockly - [plugins](/guides/contribute/samples/repository_structure#plugins), - a collection of extensions that add functionality Blockly. - -### Project - -And if you want to get even more fine-grained there are also tags for individual -projects. These are usually created for plugins, which tend to have more issues -related to them, but they can also be created for codelabs and examples. If you -have a particular project you are interested in, these labels can help you find -issues related to that project. - -To see if there is a label for the project you are interested in, see the full list of labels: - -- [`blockly` repository labels](https://github.com/RaspberryPiFoundation/blockly/labels) -- [`blockly-samples` repository labels](https://github.com/RaspberryPiFoundation/blockly-samples/labels) - -### Other - -As with any collection of things, there are a few odd-balls you should also know -about. These labels may not be as helpful when you're looking for an issue to -work on, but they can still be informative. - -- **[Triage](https://github.com/RaspberryPiFoundation/blockly-samples/labels/triage):** These - issues have yet to be properly labeled by the core team. Issues with this - label may already include another simple label like - [bug](https://github.com/RaspberryPiFoundation/blockly-samples/labels/type%3A%20bug) or - [feature request](https://github.com/RaspberryPiFoundation/blockly-samples/labels/type%3A%20feature%20request), - but it is likely that more labels will be added soon. -- **[Duplicate](https://github.com/RaspberryPiFoundation/blockly-samples/labels/duplicate):** - These issues document a problem, request, or question that is already - covered by another issue. This label tells you that you should not reply to - this issue, but instead reply to the original issue. diff --git a/packages/docs/docs/guides/contribute/get-started/pr_review_process.mdx b/packages/docs/docs/guides/contribute/get-started/pr_review_process.mdx deleted file mode 100644 index 7ae0e5c96a0..00000000000 --- a/packages/docs/docs/guides/contribute/get-started/pr_review_process.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -description: The process a pull request goes through before being merged. -title: Code review process -image: images/blockly_banner.png ---- - -# Code review process - -### Goals - -Our review process has several goals: - -- **Ensure high quality code**, in both functionality and readability. -- **Catch bugs**, because bugs happen. -- **Maintain consistent style** so that it's easy to start working in any part - of the codebase. - -All of the code that goes into -[blockly-samples](https://www.github.com/RaspberryPiFoundation/blockly-samples) and -[core Blockly](https://www.github.com/RaspberryPiFoundation/blockly) goes through review, -whether it's written by community contributors or Blockly team members. - -As reviewers, we aim to work with you to make your change as good as possible. -We ask that you, as contributors, engage in conversation with us to get your -pull requests through review and merged. - -# The Process - -The PR review process goes through a few stages: - -1. [Assignment](#assignment) -2. [Feedback](#feedback) -3. [Discussion](#discussion) -4. [Revision](#revision) -5. [Repetition](#repetition) -6. [Merge!](#merge) - -## Assignment - -When your pull request comes in, the on-call member of the Blockly team assigns -a reviewer. - -Reviewers are chosen based on expertise and to evenly distribute workload. - -It may take a few days to get a reviewer assigned, and a few more days to get a -review. Don't worry, this is normal. - -## Feedback - -During the feedback stage a reviewer leaves suggestions for changes on your PR. -These could be simple things to make your code conform to the -[Google JavaScript style guide](https://google.github.io/styleguide/jsguide.html). -Or they could be larger things like asking you to reorganize your function -definitions. - -Reviewers are encouraged to use [GitHub's code -reviews](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/reviewing-proposed-changes-in-a-pull-request#starting-a-review) (rather -than making individual comments) so that you receive a single notification -instead of several. - -## Discussion - -The discussion phase is your chance to respond to the feedback. Maybe one -of the review comments wasn't clear: now is your chance to ask for -clarification. Or maybe your reviewer requested a change, but you think it will -have repercussions: now is your chance to find a compromise. - -:::note -For this to work, both parties need to go into the discussion with a -spirit of **collaboration**. The goal is not to "win" but to make something -you're both proud of. -::: - -## Revision - -The revision phase is where you get to make changes to your PR. Usually these -changes are a result of something your reviewer has said in the feedback phase. - -Once you have completed your revisions it can be helpful to [tag](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) -your reviewer asking them to take another look. - -:::note -discussion and revision may happen at the same time. -::: - -## Repetition - -After the revision phase your reviewer has another chance to give -[feedback](#feedback), and the process starts from the beginning. - -Often a second review is simple and focuses on nits such as punctuation and code -style. But sometimes a second review can be quite big. Your first reviewer may -even ask someone else to take a look, to get a fresh perspective. - -## Merge! - -The merge phase is your chance to **celebrate**. You've created a change, -discussed and revised it, and finally gotten it merged! This is a grand -achievement that many people never start, let alone complete! - -Thank you for all of your hard work to make Blockly better. And congratulations! diff --git a/packages/docs/docs/guides/contribute/get-started/write_a_good_issue.mdx b/packages/docs/docs/guides/contribute/get-started/write_a_good_issue.mdx index d633196f37b..fbd765b41c3 100644 --- a/packages/docs/docs/guides/contribute/get-started/write_a_good_issue.mdx +++ b/packages/docs/docs/guides/contribute/get-started/write_a_good_issue.mdx @@ -6,27 +6,21 @@ image: images/blockly_banner.png # Write a good issue -All great projects are built on user feedback. Blockly uses GitHub issues to +All great projects are built on user feedback. Blockly uses GitHub Issues to track feedback. This page details how to write an issue that is easy for a developer to read and respond to, which makes it more likely that your bug report/feature request will be addressed! -## Pre-work - ### Got Questions? We love hearing your questions! But GitHub issues aren't a very good medium for them. If you have a question, head over to our [developer -forum](https://groups.google.com/g/blockly) instead. If you ask your -question there you're more likely to get a timely and thorough response because -it is filled with developers that have been using Blockly for years! +forum](https://groups.google.com/g/blockly) instead. -### Check for Duplicates +## Check for Duplicates Before you go about writing _any_ type of issue, it is always good to see if a -matching one already exists. If one does, this saves you the effort of having to -write it up yourself! So before you get started writing, do some searches for -duplicates or related issues. +matching one already exists. Do some searches for duplicates or related issues: - Search in [blockly-samples](https://github.com/RaspberryPiFoundation/blockly-samples/issues?q=is%3Aissue+mySearchHere) - Search in [Blockly core](https://github.com/RaspberryPiFoundation/blockly/issues?q=is%3Aissue+mySearchHere) @@ -37,50 +31,31 @@ detailing your thoughts. This is especially important for bug reports and feature requests. If developers see that an issue is getting a lot of attention, it is more likely to get worked on! -## Report a Bug - -So you think you've discovered a bug? Great! We love hearing bug reports because -we want this project to be as stable as possible. Here are some steps you can -follow to help your bug get fixed. - -1. [Check for Duplicates](#check-for-duplicates) -1. [Gather Evidence](#gather-evidence) -1. [Locate the Issue](#locate-the-issue) -1. [Solidify your Reproduction](#solidify-your-reproduction) -1. [Suggest a Cause](#suggest-a-cause) -1. [Write your Issue!](#write-your-issue) +## Types of issues +There are three types of issues you can file in the Blockly repo: +1. [Bug reports](#bug-reports) +1. [Feature requests](#feature-requests) +1. [Documentation problems](#documentation-problems) -### Gather Evidence +### Bug Reports Generally, the more information your bug has, the better. Here are a few things you might want to provide: -- **Screenshots or Gifs** can be really helpful if a bug causes a visual +- **A Detailed Description** of the buggy behavior is a great starting place. Be +specific about when and where you're seeing the problem. +- **Screenshots, Gifs, or Screen Recordings** can be really helpful if a bug causes a visual problem. - **Sample Code** is useful if a bug only affects certain kinds of blocks, or configurations of workspaces. - **A Hosted Site** is great if you're having trouble reproducing your bug outside your specific environment. -### Locate the Issue - -Between the core library, the plugins, the examples, and the codelabs, we've got -a lot of Blockly code. Help us out by telling us exactly where the issue is. - -If the problem is in core, which component or codelab is it in? For instance, it could be an issue -with the toolbox, or with the zoom controls, or with the library blocks. Be as -specific as possible. - -If the problem is in blockly-samples, figure out which plugin or -example it's in. If you find the same bug in multiple places, tell us that too. - -### Solidify your Reproduction +#### Solidify your Reproduction A bug is only fixable if it is reproducible, so before you submit an issue, make -sure you have a solid way of getting your bug to occur. - -You should end up with a numbered list of steps that tell a developer how to -reproduce the bug. For example: +sure you have a solid way of getting your bug to occur. You should end up with a +numbered list of steps that tell a developer how to reproduce the bug. For example: 1. Open X codelab. 1. Go to Y page. @@ -88,121 +63,84 @@ reproduce the bug. For example: 1. Observe the bad behavior, which looks like W. If your issue is in Blockly core, try to reproduce it in the -[playground](https://blockly-demo.appspot.com/static/tests/playground.html). - -### Suggest a Cause - -If you think you know why the bug is happening, include that information as +[playground](https://raspberrypifoundation.github.io/blockly/packages/blockly/tests/playground.html). +Finally, if you think you know *why* the bug is happening, include that information as well. Again, be as specific as possible. -### Write your Issue! - -The time has come to write your bug report. Select your repository: +:::info[File a bug report] +File your bug report in: +- [Blockly core](https://github.com/RaspberryPiFoundation/blockly/issues/new?template=bug_report.yaml) +- [Blockly samples](https://github.com/RaspberryPiFoundation/blockly-samples/issues/new?template=bug_report.yaml) +::: -- [Blockly core](https://github.com/RaspberryPiFoundation/blockly/issues/new?assignees=&labels=issue%3A+bug%2C+issue%3A+triage&template=bug_report.yaml) -- [Blockly-samples](https://github.com/RaspberryPiFoundation/blockly-samples/issues/new?assignees=&labels=type%3A+bug%2C+triage&template=bug_report.yaml) - -Be sure to fill out all of the sections of the issue template, even the ones -not detailed here. - -Thank you for your interest in reporting a bug, and happy issue writing! - -### What's Next? - -- Your bug report is automatically tagged for triage. -- The on-call member of the Blockly team will take a look and possibly ask - clarifying questions. They will also add labels, which we use to keep our bugs - organized. -- The issue may be marked "Help Wanted", in which case you can claim it and - start working on it. -- The issue may be assigned to a member of the Blockly team for a fix. -- The issue may be marked with a quarterly milestone, to indicate when it will - be done. -- The issue may be placed in the Icebox milestone, meaning that we do not intend - to work on it in the foreseeable future. - - This may happen for low-frequency issues or bugs with known workarounds. - - You can still work on Iceboxed issues. -- The issue may be placed in the Bug Bash Backlog milestone, meaning that it is - non-urgent but we still want to fix it. - - At the end of every quarter the team spends a few weeks working on bugs - pulled from the Bug Bash Backlog milestone. -- The issue may be moved from Blockly core to blockly-samples (or the - opposite direction) if needed. -- The issue may be closed. - -## Feature Request +### Feature Requests Is there something you want to change to make Blockly better? Do you have an -idea for a plugin, example, or codelab? Maybe there's already one you like, and -you've come up with a way to improve it. If so then you've come to the right -place! Here are steps to help you create a great feature request that gets a -response. - -1. [Check for Duplicates](#check-for-duplicates) -1. [Check the Requirements](#check-the-requirements) -1. [Gather your Thoughts](#gather-your-thoughts) -1. [Write your Feature Request!](#write-your-feature-request) +idea for a plugin, example, or codelab? If so then you may want to create a +feature request! -### Check the Requirements - -We would love to allow every single idea to enter this repository! But sadly +We would love to allow every idea to enter this repository! But sadly we're only human, so we have some guidelines in place about what kinds of -requests we will pursue. - -Here are the guidelines for each of the different categories of projects: +requests we will pursue. Here are the guidelines for some of the different categories of projects: -- [Blockly core](/guides/contribute) - [Plugins](/guides/contribute/samples/add_a_plugin#first-party-criteria) - Examples: Show how to use only one or two Blockly features. - Codelabs: Show how to complete a single task or implement a single behaviour. -But these aren't hard and fast rules. They're just meant to give you an idea of -what we're looking for before you put time into building your feature request. - +These aren't strict rules; they're meant to give you an idea of +what we're looking for before you build your feature request. If you're unsure whether something fits, try posting it on our [developer forums](https://groups.google.com/g/blockly). And remember, even if your idea doesn't get accepted, we would still love for you to build it as a third party plugin or tutorial! -### Gather your Thoughts +#### Gather your Thoughts Your idea doesn't need to be 100% fleshed out with tinsel and diagrams before -you go ahead and submit, but you should have a solid idea of what you're looking +you submit, but you should have a solid idea of what you're looking for. These are some good questions to ponder before you start to write: - Why do I want this feature? - Does this feature solve a problem? -- Who is the intended audience for this feature? -- Why does this feature serve them? +- Who is the intended audience for this feature, and how does this feature serve them? - What are some alternative options that could achieve the same thing? -Once you have those things figured out, you'll be most of the way to a good -feature request! +:::info[File a feature request] +File your feature request in: +- [Blockly core](https://github.com/RaspberryPiFoundation/blockly/issues/new?template=feature_request.yaml) +- [Blockly samples](https://github.com/RaspberryPiFoundation/blockly-samples/issues/new?template=feature_request.yaml) +::: + +### Documentation problems + +Blockly has multiple sources of documentation, including: -### Write your Feature Request! +- [Guides](/guides/get-started/what-is-blockly) +- [Codelabs](/codelabs) +- [API reference](/reference/blockly) -Now you're ready to write your feature request. Select your repository: +We want our documentation to be clear, helpful, and complete. -- [Blockly core](https://github.com/RaspberryPiFoundation/blockly/issues/new?assignees=&labels=issue%3A+feature+request%2C+issue%3A+triage&template=feature_request.yaml) -- [Blockly-samples](https://github.com/RaspberryPiFoundation/blockly-samples/issues/new?assignees=&labels=type%3A+feature+request%2C+triage&template=feature_request.yaml) +If there's something incorrect or confusing in our documentation, please file a +documentation problem to let us know. You can also file a documentation issue if +there's a new piece of documentation that you'd like to see included. For +instance, you could request a new codelab or a new page in the guides. -Be sure to fill out all of the sections of the issue template, even the ones -not detailed here. +:::info[File a documentation problem] +File any documentation issues in +- [Blockly core](https://github.com/RaspberryPiFoundation/blockly/issues/new?template=documentation.yaml) +::: -Thank you for your interest in submitting a feature request, and happy issue -writing! +## What's Next? -### What's Next? +Thank you for helping improve Blockly! After you submit your issue: +- The issue is automatically tagged with a `status: triage` label. +- The Blockly team will take a look, and add [other labels](https://github.com/RaspberryPiFoundation/blockly/labels) +to categorize the issue. +- We may ask follow-up questions and add a `status: needs more info` label to +indicate that the issue needs more information before work can begin. +- Once the `status: triage` or `status: needs more info` labels are removed, you +may start working on the issue if you'd like to. See the page on +[writing a good pull request](/guides/contribute/get-started/write_a_good_pr) +for more information on submitting code to Blockly. -- Your feature request is automatically tagged for triage. -- The on-call member of the Blockly team will take a look and possibly ask - clarifying questions. They will also add labels, which we use to keep our bugs - organized. -- The feature may be marked "Help Wanted", in which case you can claim it and - start working on it. -- The feature may be assigned to a member of the Blockly team for - implementation. -- The feature request may be moved from Blockly core to blockly-samples (or the - opposite direction) if needed. -- The feature request may be closed, in which case you still have the option to - implement it as a third-party plugin. diff --git a/packages/docs/docs/guides/contribute/get-started/write_a_good_pr.mdx b/packages/docs/docs/guides/contribute/get-started/write_a_good_pr.mdx index 85301103162..5548cf0514e 100644 --- a/packages/docs/docs/guides/contribute/get-started/write_a_good_pr.mdx +++ b/packages/docs/docs/guides/contribute/get-started/write_a_good_pr.mdx @@ -4,45 +4,44 @@ title: Write a good pull request image: images/blockly_banner.png --- -# Write a good pull request +# Write and merge a good pull request -Pull requests are like the life blood of a repository. They keep everything +Pull requests (PRs) are like the life blood of a repository. They keep everything healthy and moving. This page details how to create a PR that is complete and easy to review, which makes it more likely that your PR will get merged. -Here are steps you can take to make sure you create the best PR possible. +If this is your first time contributing to Blockly or blockly-samples, start at +the [development setup](/guides/contribute/get-started/) page. + +Here are steps you can take to make sure you create the best PR possible: 1. [Communicate](#communicate) -1. [Get Set Up](#get-set-up) -1. [Keep it Small](#keep-it-small) -1. [Keep it Clean](#keep-it-clean) -1. [Test your Change](#test-your-change) -1. [Communicate (pt2)](#communicate-1) +1. [Keep it small](#keep-it-small) +1. [Keep it clean](#keep-it-clean) +1. [Test your changes](#test-your-changes) +1. [Write a summary](#write-a-summary) +1. [Read the review](#read-the-review) +1. [Discuss, revise, and repeat](#discuss-revise-and-repeat) +1. [Merge!](#merge) -### Communicate +## Communicate Before you jump in and start writing code, it's helpful to communicate with the -core team so they know what you're interested in. +team so they know what you're interested in. If there is an issue that you are +interested in, put a comment on the issue saying you're going to start to work +on it. A team member will respond to confirm that it's yours. -If there is an issue you are interested in, put a comment on the issue saying -you're going to start to work on it. This makes sure that we don't have multiple -people working on the same thing. A team member will respond to confirm that -it's yours. +If you're not sure where to start, use the [`good first issue`](https://github.com/RaspberryPiFoundation/blockly/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) +label to find issues that are good candidates for your first contribution to Blockly. If you have an idea which is not covered by an issue, please [write one up](/guides/contribute/get-started/write_a_good_issue) before you begin work. -This gives the team a chance to discuss how best to build out the change -_before_ you start building, which saves you work in the long run. - -### Get Set Up - -If this is your first time contributing to Blockly or blockly-samples, start at -the [development setup](/guides/contribute/get-started/development_tools) page. +This gives the team a chance to determine the issue's priority and discuss how +best to build out the change _before_ you start building. -### Keep it Small +## Keep it Small -Always try to keep your changes small and focused. We would much rather review -multiple smaller PRs than review one giant PR. Some good rules of thumb are: +Keep your changes small and focused. Some good rules of thumb are: - **Fix one problem.** Don't try to tackle multiple issues at once. - **Limit the scope.** Usually a PR should take < 8hrs (depending on your @@ -50,7 +49,7 @@ multiple smaller PRs than review one giant PR. Some good rules of thumb are: - **Use commits.** If your PR feels a little big, split the changes into logical groups using git commits. -### Keep it Clean +## Keep it clean Why care about code style? We're in it for the long term, and consistent style makes maintenance easier. Style refers to how you name your variables, but also @@ -59,40 +58,67 @@ use tools such as eslint to automate style checks. In addition to eslint, please follow these guides: -- [Google JavaScript style - guide](https://google.github.io/styleguide/jsguide.html). -- [Commit Message Guide](/guides/contribute/get-started/commits) +- [Blockly style guide](/guides/contribute/core/style_guide) +- [Commit message guide](/guides/contribute/get-started/commits) - [API visibility](/guides/programming/using_blockly_apis) - [Codelab style guide](/guides/contribute/core/write_a_codelab#writing-tips) -### Test your Change +## Test your changes -Before you put up a PR you should always test that your changes are working, so -that you don't have to go back and fix things later. Here are some ideas for -testing the different categories of projects: +Before you put up a PR, you should always test that your changes are working. +That way, you don't have to go back and fix things later. You should test all of your +demonstrated functionality on the [playground](/guides/contribute/core/testing/playground). +If possible, you should also write [unit tests](/guides/contribute/core/testing/unit_testing) +covering your changes. -- For **plugins**: write automated mocha tests covering your changes. -- For **examples**: manually test all of your demonstrated functionality. -- For **codelabs**: run through the entire tutorial in a clean environment and - test any example code you provide. - -### Communicate - -This is the last and arguably the most important part of creating a PR: writing -the summary. +## Write a summary +After finishing the code, you'll need to [create the PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). +During the PR creation process, you'll write a summary describing your changes. Writing a great PR summary helps other developers review your changes, making it more likely that it will get accepted faster! -Your summary should include things like: - -- What issue your PR is related to. -- What change your PR adds. -- How you tested your change. -- Anything you want reviewers to scrutinize. -- Any other information you think reviewers need. - If you follow the PR template when your create your request you should be good to go. Just remember to be as **concise** and **complete** as possible. -Happy Coding! +## Read the review + +After your PR is submitted, it will be reviewed by a member of the Blockly team. +As reviewers, we aim to work with you to make your change as good as possible. +We ask that you, as contributors, engage in conversation with us to get your +pull requests through review and merged. All code is reviewed, regardless of +whether it is written by community contributors or Blockly team members. + +Our review process has several goals: + +- **Ensure high quality code**, in both functionality and readability. +- **Catch bugs**, because bugs happen. +- **Maintain consistent style** so that it's easy to start working in any part + of the codebase. + +## Discuss, revise, and repeat + +Reviewers will leave comments on your PR. They may suggest changes or ask questions +about the code you've written. You're welcome to ask for clarification, explain +your choices, or point out issues with a requested change. + +:::tip[Be collaborative!] +For this to work, both parties need to go into the discussion with a +spirit of **collaboration**. The goal is not to "win" but to make something +you're both proud of. +::: + +Once you and your reviewer(s) have determined next steps, you can make revisions +to your PR. GitHub will automatically update your PR if you push new commits on +the same branch. + +After revision, your reviewer may have more comments; this is completely normal! +You'll repeat this process together until the PR is approved. + +## Merge! + +Once the PR is approved, a member of the Blockly team will merge it. The merge +phase is your chance to **celebrate**. You've created a change, discussed and +revised it, and finally gotten it merged! + +Thank you for all of your hard work to make Blockly better. And congratulations! diff --git a/packages/docs/docs/guides/contribute/index.mdx b/packages/docs/docs/guides/contribute/index.mdx index c4d3689ea08..7f81508092a 100644 --- a/packages/docs/docs/guides/contribute/index.mdx +++ b/packages/docs/docs/guides/contribute/index.mdx @@ -11,9 +11,8 @@ contributions. ## How you can help -- [File bugs](/guides/contribute/get-started/write_a_good_issue) -- [File feature requests](/guides/contribute/get-started/write_a_good_issue#feature-request) -- [Fix bugs](/guides/contribute/get-started/write_a_good_pr) +- [File bugs or feature requests](/guides/contribute/get-started/write_a_good_issue) +- [Fix issues](/guides/contribute/get-started/write_a_good_pr) - [Add tests](/guides/contribute/core/unit_testing) - [Write codelabs](/guides/contribute/core/write_a_codelab) - [Write plugins](/guides/contribute/samples/add_a_plugin) @@ -31,13 +30,8 @@ contributions. ### Talk to us! -Help us focus our development efforts by telling us -[what you are doing with Blockly](https://goo.gl/forms/kZTsO9wGLmpoPXC02). The -questionnaire only takes a few minutes and will help us better support the -Blockly community. - -Or join our -[newsgroup for developers](https://groups.google.com/g/blockly) and +Join our +[forum for developers](https://groups.google.com/g/blockly) and say hello. Show us your prototypes early; collectively we have a lot of experience and can offer hints which will save you time. Plus, we always love to hear about new projects and use cases for Blockly! diff --git a/packages/docs/docs/guides/contribute/samples/add_a_plugin.mdx b/packages/docs/docs/guides/contribute/samples/add_a_plugin.mdx index e1d36245ca7..d8def83c60e 100644 --- a/packages/docs/docs/guides/contribute/samples/add_a_plugin.mdx +++ b/packages/docs/docs/guides/contribute/samples/add_a_plugin.mdx @@ -62,7 +62,7 @@ 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-request). +request](/guides/contribute/get-started/write_a_good_issue#feature-requests). In addition to the basic feature request information, a plugin suggestion should include: diff --git a/packages/docs/sidebars.js b/packages/docs/sidebars.js index 16a081a4ce9..b0681c7c980 100644 --- a/packages/docs/sidebars.js +++ b/packages/docs/sidebars.js @@ -1334,11 +1334,6 @@ const sidebars = { label: 'Overview', id: 'guides/contribute/get-started/index', }, - { - type: 'doc', - label: 'Development tools', - id: 'guides/contribute/get-started/development_tools', - }, { type: 'doc', label: 'Write a good issue', @@ -1354,21 +1349,6 @@ const sidebars = { label: 'Commit message guide', id: 'guides/contribute/get-started/commits', }, - { - type: 'doc', - label: 'Code review process', - id: 'guides/contribute/get-started/pr_review_process', - }, - { - type: 'doc', - label: 'Issue labels', - id: 'guides/contribute/get-started/issue_labels', - }, - { - type: 'doc', - label: 'Use the playground', - id: 'guides/contribute/get-started/playground', - }, ], }, { @@ -1384,54 +1364,65 @@ const sidebars = { type: 'category', label: 'Core architecture', items: [ + { + type: 'doc', + label: 'Core tour', + id: 'guides/contribute/core/core-architecture/core-tour', + }, { type: 'doc', label: 'Render management', - id: 'guides/contribute/core-architecture/render-management', + id: 'guides/contribute/core/core-architecture/render-management', }, ], }, { type: 'doc', - label: 'Style guide', - id: 'guides/contribute/core/style_guide', + label: 'Development tools', + id: 'guides/contribute/core/development_tools', }, { type: 'doc', - label: 'Build scripts', - id: 'guides/contribute/core/building', + label: 'Style guide', + id: 'guides/contribute/core/style_guide', }, { type: 'doc', - label: 'Advanced compilation', - id: 'guides/contribute/core/advanced', + label: 'Localization and translation', + id: 'guides/contribute/core/localization_and_translation', }, { type: 'category', - label: 'Localization', + label: 'Testing', items: [ { type: 'doc', - label: 'Add a new localization token', - id: 'guides/contribute/core/add_localization_token', + label: 'Use the playground', + id: 'guides/contribute/core/testing/playground', + }, + { + type: 'doc', + label: 'Unit tests', + id: 'guides/contribute/core/testing/unit_testing', }, + ], + }, + { + type: 'category', + label: 'Building and compilation', + items: [ { type: 'doc', - label: 'Translate text', - id: 'guides/contribute/core/translating', + label: 'Build scripts', + id: 'guides/contribute/core/building_and_compilation/building', }, { type: 'doc', - label: 'Klingon', - id: 'guides/contribute/core/klingon', + label: 'Advanced compilation', + id: 'guides/contribute/core/building_and_compilation/advanced', }, ], }, - { - type: 'doc', - label: 'Unit tests', - id: 'guides/contribute/core/unit_testing', - }, { type: 'doc', label: 'Write a codelab', diff --git a/packages/docs/static/_redirects b/packages/docs/static/_redirects index 5ab018c4ed9..66cbede1c32 100644 --- a/packages/docs/static/_redirects +++ b/packages/docs/static/_redirects @@ -37,12 +37,12 @@ # Contributing Get Started section /guides/modify/contribute/commits /guides/contribute/get-started/commits/ 301 -/guides/modify/development_setup /guides/contribute/get-started/development_tools/ 301 -/guides/modify/contribute/issue_labels /guides/contribute/get-started/issue_labels/ 301 -/guides/modify/contribute/pr_review_process /guides/contribute/get-started/pr_review_process/ 301 +/guides/modify/development_setup /guides/contribute/core/development_tools/ 301 +/guides/modify/contribute/issue_labels https://github.com/RaspberryPiFoundation/blockly/labels 301 +/guides/modify/contribute/pr_review_process /guides/contribute/get-started/write_a_good_pr/#read-the-review 301 /guides/modify/contribute/write_a_good_issue /guides/contribute/get-started/write_a_good_issue/ 301 /guides/modify/contribute/write_a_good_pr /guides/contribute/get-started/write_a_good_pr/ 301 -/guides/modify/web/playground /guides/contribute/get-started/playground/ 301 +/guides/modify/web/playground /guides/contribute/core/testing/playground/ 301 # Contributing to Samples section /guides/modify/contribute/add_a_plugin /guides/contribute/samples/add_a_plugin/ 301 @@ -54,9 +54,22 @@ # Contributing to Core section /guides/modify/web/style-guide /guides/contribute/core/style_guide/ 301 -/guides/modify/web/unit-testing /guides/contribute/core/unit_testing/ 301 +/guides/modify/web/unit-testing /guides/contribute/core/testing/unit_testing/ 301 /guides/modify/web/* /guides/contribute/core/ 301 +# Reorganize contribute docs +/guides/contribute/core/advanced /guides/contribute/core/building_and_compilation/advanced/ 301 +/guides/contribute/core/building /guides/contribute/core/building_and_compilation/building/ 301 +/guides/contribute/core-architecture/render-management /guides/contribute/core/core-architecture/render-management/ 301 +/guides/contribute/get-started/development_tools /guides/contribute/core/development_tools/ 301 +/guides/contribute/core/unit_testing /guides/contribute/core/testing/unit_testing/ 301 +/guides/contribute/get-started/playground /guides/contribute/core/testing/playground/ 301 +/guides/contribute/core/add_localization_token /guides/contribute/core/localization_and_translation/ 301 +/guides/contribute/core/translating /guides/contribute/core/localization_and_translation/#translate-text 301 +/guides/contribute/core/klingon /guides/contribute/core/localization_and_translation/#klingon-translations 301 +/guides/contribute/get-started/issue_labels https://github.com/RaspberryPiFoundation/blockly/labels 301 +/guides/contribute/get-started/pr_review_process /guides/contribute/get-started/write_a_good_pr/#read-the-review 301 + # Advanced Customization section (under Configure) /guides/plugins/interfaces/overview /guides/configure/customization/ 301 /guides/plugins/interfaces/connection_checker /guides/create-custom-blocks/inputs/connection_checker/ 301