Define what approving a PR means

CONTRIBUTING.md

@@ -1,64 +1,64 @@
 # Contributing extensions
 
-Before you submit extensions, please read the custom extension tutorial **in full**:
+To learn how to write custom extensions, see our documentation:
 
  - https://docs.turbowarp.org/development/extensions/introduction
+ - https://docs.turbowarp.org/development/extensions/unsandboxed
+ - https://docs.turbowarp.org/development/extensions/compatibility
+ - https://docs.turbowarp.org/development/extensions/better-development-server
+ - and more in the sidebar of those pages
 
-Please pay special attention to:
+The rest of this page is about this specific repository.
 
- - Unsandboxed extensions: https://docs.turbowarp.org/development/extensions/unsandboxed
- - Maintaining backward compatibility: https://docs.turbowarp.org/development/extensions/compatibility
- - A better development server: https://docs.turbowarp.org/development/extensions/better-development-server
+## Acceptance criteria
 
-Read this document **in full** too. Pull requests that don't follow the guidelines will take *much* longer to be reviewed.
+These categories of extensions are **highly discouraged**:
 
-## Acceptance criteria
+ - Broad "Utilities" extensions. Break them up into multiple extensions instead. See https://github.com/TurboWarp/extensions/issues/674 for discussion.
+ - Extensions that are very similar to existing ones. Consider modifying the existing extension instead.
+ - Very niche extensions. You can write the extension for yourself, then import it as a file instead without needing us to review.
+ - Extensions whose primary purpose is monetization. It isn't in the spirit of a free and open source project.
+ - Joke extensions. Things that are funny to you are not funny to everyone, especially when we get bug reports about it.
 
-Strictly, nothing is banned, but the following are *highly* discouraged:
+Some extensions were added before these guidelines existed. We're trying to enforce them moving forward.
 
- - Broad "Utilities" extensions (break them up into multiple extensions, see https://github.com/TurboWarp/extensions/issues/674)
- - Extensions that are very similar to existing ones (consider modifying the existing one instead)
- - One-use personal extensions (load the extension as a local file instead)
- - Extensions whose primary purpose is monetization (not in the spirit of an open source project)
- - Joke extensions (they aren't funny when they cause us to get bug reports)
+## Security
 
-Some extensions were added before these rules existed. That doesn't mean you will be exempted too.
+TurboWarp's threat model is that loading a project in the editor should be no more dangerous than opening a PowerPoint. Projects can't affect anything outside of the editor without consent from the user. We offer a [bug bounty](https://github.com/TurboWarp/extensions/security/policy) to people who find and report security bugs in merged extensions. Most guardrails can disappear once the project is packaged.
+
+Evaluating project-supplied JavaScript using `eval()`, `new Function()`, or other methods is not allowed.
 
 ## Important context
 
-Every merged extension is more code that we will be expected to maintain indefinitely, even if you disappear. Remember: broken extensions mean that real projects by real people no longer work. If the renderer is rewritten one day, we will have to ensure that extensions like Clipping & Blending, RGB Channels, and Augmented Reality still work. That's not a small commitment.
+Every merged extension is more code that we are expected to maintain indefinitely, even if you disappear. Broken extensions mean that real projects by real people no longer work. If the renderer is rewritten one day, we will have to ensure that extensions like Clipping & Blending, RGB Channels, and Augmented Reality still work. That's not a small commitment.
 
 We're all volunteers who all have lives outside of TurboWarp extensions. Many have full time jobs or are full time students. We'll get to you as soon as we can, so please be patient.
 
-Every extension is also covered under [our bug bounty](https://github.com/TurboWarp/extensions/security/policy), so mindlessly merging things will have a direct impact on my wallet.
-
-## Writing extensions
+## Writing and organizing extensions
 
-Extension source code goes in the [`extensions`](extensions) folder. For example, an extension placed at `extensions/hello-world.js` would be accessible at [http://localhost:8000/hello-world.js](http://localhost:8000/hello-world.js) using our development server.
+This repository contains a custom development server. Extension source code goes in the [`extensions`](extensions) folder. For example, an extension placed at `extensions/hello-world.js` would be accessible at [http://localhost:8000/hello-world.js](http://localhost:8000/hello-world.js) when you start the development server.
 
-New extensions should be added in a user folder. You can name your folder anything you want; common choices are your GitHub username or your Scratch username. If your username is `TestMuffin123`, then `TestMuffin123`, `TestMuffin`, or even just `Muffin` would all be accepted -- we are very lenient about this. Do note that user folders are just for organization; other people are still allowed to edit your extension. Renaming your folder later is only allowed in very rare circumstances, so please get it right the first time.
-
-Extensions must be self-contained. All libraries and hardcoded resources should be embedded into the extension's JavaScript file. If you include minified code, please link where to find the unminified code and include a copy of the original license.
+New extensions should be added in a user folder. You can name your folder anything you want; common choices are your GitHub username or your Scratch username. You can largely choose whatever you want. These folders are just for organization; other people are still allowed to edit your extension. Folder name changes are only granted in rare circumstances, so please get it right the first time.
 
 ## License
 
 **We are not lawyers. This is not legal advice.**
 
-Everything in this repository must be available under an open source license. You can use any license you want, but we **STRONGLY** recommend using the [Mozilla Public License verison 2.0](licenses/MPL-2.0.txt) for all new extensions.
+Everything in this repository must be available under an open source license. You can use any license you want, but we recommend using the [Mozilla Public License verison 2.0](licenses/MPL-2.0.txt) for all new extensions.
 
-The following licenses are banned for being [incompatible the GPLv3](https://www.gnu.org/licenses/license-list.en.html), so do not use any code, images, etc. under them:
+All extension are included in TurboWarp Desktop which is licensed under the GPLv3. Thus, you need to use [a license that is compatible with GPLv3](https://www.gnu.org/licenses/license-list.en.html). This excludes:
 
  - Creative Commons Attribution-ShareAlike licenses prior to version 4.0
-   - This includes user-generated content on the Scratch website which [uses version 2.0](https://scratch.mit.edu/terms_of_use) of this license.
+   - This includes user-generated content on the Scratch website which [uses version 2.0](https://scratch.mit.edu/terms_of_use).
    - This includes StackOverflow posts contributed before 2018-05-02 which [use several different versions](https://stackoverflow.com/help/licensing).
- - Creative Commons Attribution-NoDerivs and similar "no derivatives" licenses
- - Creative Commons Attribution-NonCommercial and similar "non commercial" or "personal use only" licenses
+ - "No derivatives" licenses such as Creative Commons Attribution-NoDerivs
+ - "Non commercial" or "personal use only" licenses such as Creative Commons Attribution-NonCommercial
 
-Once you choose a license for your extension, [find its SPDX identifier from this table](https://spdx.org/licenses/). The "FSF Free/Libre?" and "OSI Approved?" columns should both contain "Y".
+Once you choose a license for your extension, [find its SPDX identifier from this table](https://spdx.org/licenses/). The "FSF Free/Libre?" and "OSI Approved?" columns should both contain "Y". You'll need to include the identifier in the extension's metadata.
 
 ## Metadata
 
-All extensions should need a metadata comment at the *very* start of the file, before any code. We have a script that will read these, so to make sure it understands what you write, use this exact format:
+All extensions need a metadata comment at the start of the file, before any code. This section gets read by a script, so make sure to follow the format closely.
 
 ```js
 // Name: My Cool Extension
@@ -71,33 +71,58 @@ All extensions should need a metadata comment at the *very* start of the file, b
 
 You must use line comments; block comments `/* */` will not work. These fields are **REQUIRED**:
 
- - `Name` will appear on the website. It should be similar to the name returned by getInfo().
- - `ID` should be identical to the id returned by getInfo().
- - `Description` will appear on the website.
- - `License` describes the license that the extension's code is under. It should be a valid [SPDX license](https://spdx.org/licenses/) expression. (use `MPL-2.0` if you are unsure)
+ - `Name` appears on the website and in the library. It should be similar to the `name` returned by getInfo().
+ - `ID` must be identical to the `id` returned by getInfo().
+ - `Description` appears on the webstie and in the library.
+ - `License` describes the license that the extension's code is under. It must be a valid [SPDX license](https://spdx.org/licenses/) expression. For the Mozilla Public License verison 2.0 that we recommend, the identifier is `MPL-2.0`.
 
-`By` is optionally used to credit the author of the extension (you!). `Original` is used if the extension is based on or ported from somewhere else. They both use the same format of `Name` or `Name <https://scratch.mit.edu/users/username>`. Links to places other than Scratch are not allowed at this time. You can repeat both of these as many times as needed, just add another `// By: ...` comment after.
+`By` allows you to credit yourself. `Original` is used if the extension is based on another person's work. They both use the same format of `Name` or `Name <https://scratch.mit.edu/users/username>`. Links to places other than Scratch are not allowed at this time. You can repeat both of these as many times as needed, just add another `// By: ...` comment.
 
-In addition to `// License: ...`, you can also add a larger block comment with more information if you want to.
+## Translations
 
-## Website stuff
+Extensions should support being translated into any language. The development server and [volunteer translators](https://docs.turbowarp.org/translate) will handle the hard part. The developer's job is to use `Scratch.translate()` for any string that should be translated, such as block text or labels. Here's some examples to explain the idea:
 
-Add your extension's path (without `extensions/` and without `.js`) to `extensions/extensions.json`. The order of that list determines the order of the library. Don't worry about putting it in the right spot, we'll move it if we disagree.
+```js
+// For simple strings that can be understood without additional context,
+// call Scratch.translate with your string directly:
+Scratch.translate("stage width")
+
+// The translation system handles block inputs properly, so use the same process:
+Scratch.translate("move [STEPS] steps")
+
+// If your string needs some context to understand properly, call
+// Scratch.translate with an object:
+Scratch.translate({
+  default: "map",
+  description: "A map in the computer science sense. Maps keys to values. Sometimes called a dictionary."
+})
+
+// If your string needs to fill in a value that isn't known until runtime,
+// use a placeholder. Don't try to concatenate strings yourself as that is
+// confusing and not all languages have the same grammar structure.
+Scratch.translate({
+  default: "Hello, {name}!",
+  description: "{name} is replaced with the user's name"
+}, {
+  name: "world"
+})
+```
 
-New extensions do not *need* images, but they are encouraged. Save the image in the `images` folder with the same folder name and file name (but different file extension) as the extension's source code. For example, if your extension is located in `extensions/TestMuffin/fetch.js`, save the image as `images/TestMuffin/fetch.svg` or `images/TestMuffin/fetch.png`. The homepage generator will detect it automatically. Images are displayed in a 2:1 aspect ratio. SVG (preferred), PNG, or JPG are accepted. PNG or JPG should be 600x300 in resolution. Please add proper attribution to `images/README.md` for *any* resources that were not made by you. The resulting image must be licensed under the [GNU General Public License version 3](licenses/GPL-3.0.txt).
+All translators will see is the extension's name and description, the English text, and any description you add.
 
-Most extensions shouldn't need external documentation -- it should be obvious what to do just by looking at the blocks. That said, some do need more explanation. Documentation is written in markdown and placed in the `docs` folder with a similar layout to images. For example, documentation for `extensions/TestMuffin/fetch.js` would be saved as `docs/TestMuffin/fetch.md`. Our version of markdown is slightly extended to allow rendering [scratchblocks](https://scratchblocks.github.io/). Just look at the existing documentation for syntax examples. It's not a perfect experience: block colors have to be manually copied, and icons aren't supported, but it's better than what we had before. Once you put your markdown there, you can set a `docsURI` like `https://extensions.turbowarp.org/TestMuffin/fetch`.
+## Third-party libraries
 
-Static resources such as example resources used by extensions go in the `website` folder.
+First, try to avoid using third-party libraries if you can. If you must, we have a custom dependency system for extensions called `Scratch.external`. It's somewhat in flux but the type definitions should make it clear enough how to use.
 
-## Banned APIs
+## Adding your extension to the library
 
-Don't use these:
+Add your extension's path (without `extensions/` and without `.js`) to `extensions/extensions.json`. The order of that list determines the order of the library. Try to put it next to related related extensions if possible.
 
- - `eval()`
- - `new Function()`
- - untrusted or remote `<script>` or `<iframe>`
- - other arbitrary JS/CSS/HTML evaluation
+New extensions do not need an image for the library, but they are encouraged. Put any image in the `images` folder with the same folder name and file name but different file extension as the extension's JavaScript. For example, if your extension's code is in `extensions/TestMuffin/fetch.js`, the image would be `images/TestMuffin/fetch.svg` or `images/TestMuffin/fetch.png`. The homepage generator will find this file automatically. Images are displayed in a 2:1 aspect ratio. SVG (preferred), PNG, or JPG are accepted. PNG or JPG should be 600x300 in resolution. Add attribution to `images/README.md` for yourself and anything not made by you. Images submitted to this repository must be licensed under the [GNU General Public License version 3](licenses/GPL-3.0.txt). Avoid text if possible since these images can't be translated.
+
+Most extensions shouldn't need external documentation -- it should be obvious what to do just by looking at the blocks. That said, some do need more explanation. Documentation is written in markdown and placed in the `docs` folder with a similar layout to images. For example, documentation for `extensions/TestMuffin/fetch.js` would be `docs/TestMuffin/fetch.md`. Our version of markdown is extended to allow rendering [scratchblocks](https://scratchblocks.github.io/). Just look at the existing documentation for syntax examples. It's not a perfect experience: block colors have to be manually copied, and icons aren't supported, but it's better than what we had before. Once you put your markdown there, you can set a `docsURI` like `https://extensions.turbowarp.org/TestMuffin/fetch`.
+
+Static resources such as example resources used by extensions go in the `website` folder. They are copied to the final website without any additional processing.
 
 ## Type checking
 
@@ -107,32 +132,26 @@ If you encounter a TypeScript error, as long as you understand the error, feel f
 
 ## Linting, validation, and formatting
 
-All pull requests are automatically checked by a combination of custom validation scripts, [ESLint](https://eslint.org/), and [Prettier](https://prettier.io/). Don't worry about passing these checks on the first attempt -- most don't. That's why we have these checks.
+All pull requests are automatically checked by a combination of custom validation scripts, [ESLint](https://eslint.org/), and [Prettier](https://prettier.io/). Don't worry about passing these checks on the first attempt -- most don't. That's why we have these checks. Click on the failing check to view more details about what failed. All checks will tell you which file failed and usually some additional explanation.
 
-Our custom validation scripts do things like making sure you have the correct headers at the start of your extension and that the images are the right size. **Your extension must pass validation.** You can run them locally with:
+Our custom validation scripts do things like making sure you have the correct headers at the start of your extension and that the images are the right size. **Your extension must pass validation.** The errors will tell you what file failed and why to help you fix it. You can run these checks locally with:
 
 ```bash
 npm run validate
 ```
 
-ESLint detects common JavaScript errors such as referencing non-existant variables. **Your extension must pass linting.** You can run it locally with:
+ESLint detects common JavaScript errors such as referencing non-existant variables as well as extension-specific issues such as fetching a resource without using Scratch.fetch(). **Your extension must pass linting.** You are allowed to [disable ESLint warnings and errors](https://eslint.org/docs/latest/use/configure/rules#disabling-rules), with proper justification. You can run ESLint locally with:
 
 ```bash
 npm run lint
 ```
 
-You are allowed to [disable ESLint warnings and errors](https://eslint.org/docs/latest/use/configure/rules#disabling-rules) as needed, but please only do so if actually required.
-
-When including third-party code, especially minified code, you may use `/* eslint-disable*/` and `/* eslint-enable */` markers to disable linting for that entire section.
-
-We use Prettier to ensure consistent code formatting. **Your extension does not need to pass format; we will fix it for you if linting and validation pass.** You can format your code automatically with:
+We use Prettier to ensure consistent code formatting. You can format your pull request by commenting "!format" on it then waiting a couple minutes for the bot to process it, or you can format your code locally with:
 
 ```bash
 npm run format
 ```
 
-To just check formatting, use:
+## Internal processes
 
-```bash
-npm run check-format
-```
+Extension review: [REVIEW_PROCESS.MD](./REVIEW_PROCESS.md).