diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 96b706319c..f0f96be4c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing extensions -Before you submit extensions, please read the NEW custom extension tutorial in full: +Before you submit extensions, please read the custom extension tutorial **in full**: - https://docs.turbowarp.org/development/extensions/introduction @@ -10,76 +10,58 @@ Please pay special attention to: - Maintaining backward compatibility: https://docs.turbowarp.org/development/extensions/compatibility - A better development server: https://docs.turbowarp.org/development/extensions/better-development-server -Pull requests that don't follow the guidelines outlined in these documents tend to take much longer to be reviewed and merged. +Read this document **in full** too. Pull requests that don't follow the guidelines will take *much* longer to be reviewed. -## Local development server +## Acceptance criteria -We recommend using our local development server: +Strictly, nothing is banned, but the following are *highly* discouraged: -```bash -# Clone the repository -git clone https://github.com/TurboWarp/extensions.git -cd extensions - -# Install dependencies -npm ci - -# Start development server -npm run dev -``` - -This starts an HTTP server on [http://localhost:8000/](http://localhost:8000/) in development mode which adds a couple of extra tools to the homepage. - -After installing npm dependencies, TypeScript aware editors such as Visual Studio Code will give you smart autocomplete suggestions for most Scratch and extension APIs based on [@turbowarp/types](https://github.com/TurboWarp/types) and [@turbowarp/types-tw](https://github.com/TurboWarp/types-tw). Note that these types are not perfect; some methods are missing or incorrect. Please report any issues you find. + - 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) + - Joke extensions (they aren't funny when they cause us to get bug reports) -If you encounter a TypeScript error, as long as you understand the error, feel free to add `// @ts-ignore`, `// @ts-expect-error`, or just ignore the error entirely. We currently do not require extensions to pass type checking. - -## Alternative development server - -If for some reason you can't set up our local development server, you can start any other HTTP server in the `extensions` folder. You won't get some of the nice things our server has, but it may be good enough. If you have Python 3 installed this is very simple: - -```bash -cd extensions -python3 -m http.server -``` +Some extensions were added before these rules existed. That doesn't mean you will be exempted too. -Note that browsers tend to aggressively cache JavaScript files that don't opt out of caching as our development server does, so you may have to do hard reloads to ensure that changes to your scripts are applied. +## Important context -## Types of extensions we accept +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. -We strive to be tolerant of accepting almost any extension, including one-use novelty extensions or extensions that are similar to ones that already exist. +We're all volunteers who all have lives outside of Scratch 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. -Extensions end up in one of these categories depending on various qualities: +## Writing extensions - - Extensions that are in the repository, but not listed on the website - - Extensions that are listed on the website - - Extensions that are listed in the editor's builtin extension library +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. -## Writing extensions +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. -Extension source code goes in the `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). +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 your GitHub username, your Scratch username, or something else. For example, if your GitHub username is "TestMuffin", you could make a `TestMuffin` folder inside of the `extensions` folder and put your extensions inside there. You could then access a file placed at `extensions/TestMuffin/hello-world.js` at [http://localhost:8000/TestMuffin/hello-world.js](http://localhost:8000/TestMuffin/hello-world.js). +Static resources go in the `website` folder. This is where some example assets used by extensions such as fetch are placed. This is also where documentation goes for now, though we are in the process of modernizing that. -Static resources go in the `website` folder. This is where some example resources used by extensions such as fetch are placed. It works similarly to the `extensions` folder. +To add an extension to the website homepage, modify [`website/index.ejs`](website/index.ejs). See the existing entries for a template to copy. Place your extension wherever you want in the list. We will move it for you if we disagree. -Extensions must not use `eval()`, `new Function()`, untrusted `