Skip to content

Commit

Permalink
Update CONTRIBUTING.md (#797)
Browse files Browse the repository at this point in the history
  • Loading branch information
@GarboMuffin
GarboMuffin authored Jul 29, 2023
1 parent 8ea9528 commit 633f02a
Showing 1 changed file with 57 additions and 66 deletions.
123 changes: 57 additions & 66 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -9,77 +9,61 @@ Please pay special attention to:
- 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
- Maintaining compatibility: https://docs.turbowarp.org/development/extensions/compatibility

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)
- Novelties or 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 break. If the renderer is rewritten one day, we will have to ensure that extensions like Clipping and 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`, `TestMuffin123`, `TestMuffin` and `Muffin` are all 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 isn't something we allow (rare exceptions, open an issue), 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 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 `<script>` or `<iframe>` tags, or similar arbitrary JS/CSS/HTML/etc.
New extensions do not need images, but they are highly 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.

Extensions must be self-contained. All libraries and hardcoded resources it needs should be embedded into the extension's JavaScript file. If you include minified code, please link where to find the unminified code.
## Banned APIs

To add an extension to the website homepage, modify `website/index.ejs`. Copy one of the existing extensions. New extensions should usually be added to the end of the list.
(subject to change)

To add an image for your extension on the homepage, put a file in the `images` folder with the same name and directory structure (but a different file extension) as the extension's source code. The homepage generator will automatically update the image if you did it correctly. Images will be 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.
- `eval()`
- `new Function()`
- untrusted `<script>`
- untrusted `<iframe>`
- other arbitrary JS/CSS/HTML evaluation

## License

**We are not lawyers. This section should not be interpreted as legal advice.**
**We are not lawyers. This is not legal advice.**

The source code of the extension and any libraries it uses must be available under a permissive open source license that is compatible with the [GNU General Public License version 3](licenses/GPL-3.0.txt) so that we can include it in the desktop app. If unsure, use the [MIT License](licenses/MIT.txt). For this to be legally possible, either you must have written the entire extension yourself or have permission to use all of its components under an open source license.
The source code of the extension and any libraries it uses must be available under a permissive open source license that is compatible with the [GNU General Public License version 3](licenses/GPL-3.0.txt). This allows us to include it in TurboWarp Desktop and allows packaged projects to use your extension. If you're unsure, use our default: the [MIT License](licenses/MIT.txt). For this to be legally possible, either you must have written the entire extension yourself or have permission to use all of its components under a compatible open source license.

If you use a license other than MIT, leave a comment at the top of each file indicating its license. For example, if you prefer to use Apache 2.0, add a comment like the one below. Extensions using the default MIT License do not need to include this type of comment, but you can include one if you want.
If you use the default MIT license as we recommend, you don't need to add a comment (you can if you want to, though). If you wish to use a different license, leave a comment at the top of the file. For example, if you prefer Apache 2.0, add a comment like the one below.

```js
// (Remember: You don't need to include this if you just use the default license!)
/*!
* Copyright 2023 Your Name Here
*
Expand All @@ -97,52 +81,59 @@ If you use a license other than MIT, leave a comment at the top of each file ind
*/
```

Please update the copyright year and name appropriately. Pseudonyms are accepted. Add a copy of the full plain text license in the `licenses` folder if a copy doesn't already exist. You should use `/*!` instead of `/*` for license comments so that JavaScript minifiers won't remove it.

We don't want extension code to use the GPLv3 or LGPLv3 licenses exclusively. Our non-lawyer understanding suggests that the copyleft could extend to projects that use the extension and to any packaged projects, neither of which we want.
Update the copyright year and name appropriately. Pseudonyms are accepted. Add a copy of the full plain text version of the license in the `licenses` folder if it isn't already in there. You should use `/*!` instead of `/*` for license comments so that JavaScript minifiers won't remove it.

Extension images in the [images](images) directory are instead licensed under the [GNU General Public version 3](licenses/GPL-3.0.txt).

Please avoid code and image assets that are under these licenses as they are not compatible with the GPLv3:
## Banned licenses

You **MUST** avoid using any code or images under these licenses as we believe they are incompatible with the GPLv3:

- Creative Commons Attribution-ShareAlike licenses prior to version 4.0
- User-generated content on the Scratch website uses version 2.0 of this license.
- StackOverflow uses [different versions of this license depending on what when the post was made](https://stackoverflow.com/help/licensing).
- 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 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" licenses
- This list is non-comprehensive
- More information: https://www.gnu.org/licenses/license-list.en.html

## Suggested code style
We take licenses very seriously. License violations are one of the few things that can force us to break project compatibility.

## Code style

Our preferred code style is:

- Indent with 2 spaces
- Use semicolons
- We don't care which type of quotes you use
- Use whitespace liberally
- Comment liberally, but don't just re-explain what the code literally says (`var x = 3; // set x to 3` is a bad comment)
- Pick one type of quotes and be consistent (if unsure, we like single quotes)

## Automated linting
## Type checking

We use ESLint to automatically find problems in pull requests. To run our linting rules locally:
If you use our development server, 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.

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.

## Linting

We use ESLint to automatically common problems in pull requests. To run our linting rules on your computer, run:

```bash
npm run lint
```

To run ESLint's automatic fixes for common style issues:
ESLint can automatically fix certain issues. You can run this with:

```bash
npm run fix
```

Our linting is not intended to be overbearing -- we just want to prevent common mistakes and encourage writing readable code. If one of the rules is getting in your way, feel free to just disable it for that line or section.

When including third-party code, especially minified code, you may use [`/* eslint-disable*/` and `/* eslint-enable */`](https://eslint.org/docs/latest/user-guide/configuring/rules#disabling-rules) markers to disable linting for that section.

## Updating extensions
Our ESLint configuration separates between *warnings* and *errors*. They both cause big red error messages to appear on pull requests, but they are different:

Please make note of everything on this page: https://docs.turbowarp.org/development/extensions/compatibility
- Warnings are typically minor style issues. If you ignore these we will fix it ourselves. This usually takes 15 seconds to address.
- Errors are actually problems. Please read and address all of them. Extensions with errors may take longer to review as your extension is unfinished.

When editing extensions made by other people, please ping the person who owns its user folder, if it's in one.
You are allowed to [disable warnings or errors](https://eslint.org/docs/latest/use/configure/rules#disabling-rules) as needed, but only if actually required.

If you need to break compatibility, you can submit a "v2" version of the extension and leave the original unchanged.
When including third-party code, especially minified code, you may use `/* eslint-disable*/` and `/* eslint-enable */` markers to disable linting for that entire section.

0 comments on commit 633f02a

Please sign in to comment.