forked from babel/minify
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(contributing): move to docs directory [skip ci] (babel#735)
* docs(contributing): move to docs directory [skip ci] + Add docs about fixtures testing + Add some getting-started docs * Address some comments [skip ci] * Update tests.md [skip ci]
- Loading branch information
Showing
7 changed files
with
248 additions
and
154 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,163 +1,20 @@ | ||
## Contributing | ||
# Contributing | ||
|
||
### Requirements | ||
Contributions are always welcome, no matter how large or small. Before contributing, please read the [code of conduct](CODE_OF_CONDUCT.md). | ||
|
||
+ node >= 4 | ||
+ [yarn](https://yarnpkg.com) >= 1.0.0 (with yarn workspaces support) | ||
Much of the [prelude of Babel's Contributing guide](https://github.com/babel/babel/blob/master/CONTRIBUTING.md) also applies here since babel-minify is just a set of babel plugins, a preset and tools built on top of these things with babel itself. | ||
|
||
### Setup | ||
```sh | ||
git clone https://github.com/babel/minify | ||
cd minify | ||
``` | ||
## Useful links | ||
|
||
### Install | ||
+ [AST Explorer](https://astexplorer.net) | ||
+ [Babel plugin handbook](https://github.com/thejameskyle/babel-handbook/blob/master/translations/en/plugin-handbook.md#babel-plugin-handbook) | ||
|
||
```sh | ||
yarn | ||
``` | ||
## Chat | ||
|
||
#### Build | ||
Feel free to check out the [#minify](https://babeljs.slack.com/messages/minify/) channel on our Slack. You can request access here - https://slack.babeljs.io | ||
|
||
To build **once**: | ||
## Developing | ||
|
||
```sh | ||
yarn build | ||
``` | ||
To help develop babel-minify, check out the [`docs/`](docs) directory. | ||
|
||
Or to do an incremental build in watch mode: | ||
|
||
```sh | ||
yarn watch | ||
``` | ||
|
||
#### Lint | ||
|
||
This project uses [prettier](https://github.com/prettier/prettier) for formatting code and [eslint](https://github.com/eslint/eslint) for other linting. | ||
|
||
```sh | ||
yarn lint | ||
``` | ||
|
||
##### Lint Fix | ||
|
||
To fix formatting and other auto-fixable eslint errors, | ||
|
||
```sh | ||
yarn fix | ||
``` | ||
|
||
#### Test | ||
|
||
To run all tests, | ||
|
||
```sh | ||
yarn test | ||
``` | ||
|
||
To run tests for a specific package, | ||
|
||
```sh | ||
yarn test packages/babel-preset-minify | ||
``` | ||
|
||
#### Smoke Tests | ||
|
||
Prepare: | ||
|
||
```sh | ||
git submodule init | ||
git submodule update | ||
``` | ||
|
||
Run: | ||
|
||
```sh | ||
node smoke/run.js [options] [inputTests...] | ||
``` | ||
|
||
Usage: | ||
|
||
``` | ||
Usage: run [options] [inputTests...] | ||
Options: | ||
-h, --help output usage information | ||
-i --skip-install Skip Install Step | ||
-b --skip-build Skip Build step | ||
-c --skip-cleanup Skip cleanup step | ||
-q --quiet Quiet mode | ||
``` | ||
|
||
Example: | ||
|
||
To build and test `lodash`, | ||
|
||
```sh | ||
node smoke/run.js lodash | ||
``` | ||
|
||
To run smoke test without re-building and re-installing again | ||
|
||
```sh | ||
node smoke/run.js -ib lodash | ||
``` | ||
|
||
#### Benchmarks | ||
|
||
[benchmark.js](https://github.com/babel/minify/blob/master/scripts/benchmark.js) compares BabelMinify with [Uglify](https://github.com/mishoo/UglifyJS2), [Closure Compiler](https://github.com/google/closure-compiler) and [Closure Compiler JS](https://github.com/google/closure-compiler-js) | ||
|
||
```sh | ||
./scripts/benchmark.js [file...] | ||
``` | ||
|
||
[plugin-timing.js](https://github.com/babel/minify/blob/master/scripts/plugin-timing.js) is used to calculate and compare the time spent in each plugin. | ||
|
||
```sh | ||
./scripts/plugin-timing.js file.js | ||
``` | ||
|
||
[plugin-contribution.js](https://github.com/babel/minify/blob/master/scripts/plugin-contribution.js) calculates how much each plugin of babel-minify contributes to size reduction. | ||
|
||
```sh | ||
./scripts/plugin-contribution.js file.js | ||
``` | ||
|
||
### Debugging | ||
|
||
In your project, if you find that there is a bug that appears ONLY when you use BabelMinify, it's most likely that there is a bug in BabelMinify and you should definitely report it. Here are some guidelines that might help you drill down the issue. If it doesn't help you, you can of course create a minimal repro project with the bug and report it. | ||
|
||
#### Compile time Errors | ||
|
||
If you get a syntax error at compile time, then it could be a few things: | ||
|
||
1. The parser itself doesn't handle the syntax being used (a [babylon](https://github.com/babel/babylon) bug). | ||
2. The code is actually invalid syntax. | ||
3. You didn't turn on the relevant Babel plugin for that syntax (if experimental). | ||
|
||
If the syntax error occurs at runtime, it likely means the code generator ([babel-generator](https://github.com/babel/babel/tree/master/packages/babel-generator)) has a bug and has output invalid code. | ||
|
||
#### Runtime errors | ||
|
||
When you run your minified code in the browser, | ||
|
||
1. If there is an error in the console, as a first step, look around the code block where the error happens, and the code block of a few steps up in the stack. | ||
2. Try to predict what caused the error and try relating it to some of the plugin names in the [packages/](https://github.com/babel/minify/tree/master/packages) directory. The major ones (that do a lot of transformations) are - mangle, deadcode-elimination and simplify. | ||
3. Every plugin that Babel-Minify uses has an option in preset to toggle it on/off - [preset-options](https://github.com/babel/minify/tree/master/packages/babel-preset-minify#options) | ||
4. Disable any transformation(s) that you suspect are causing problems. Turning OFF mangling (`mangle: false`) is a good practice if you don't think it's related to a mangling bug, since unmangled variable names will make debugging easier. | ||
5. Sometimes it might NOT be a bug with one plugin but a combination of plugins. Again, `deadcode-elimination` and `simplify` maybe good candidates to start with here as they perform many transformations. | ||
6. Sometimes it might because of the [unsafe transformations](https://github.com/babel/minify/tree/master/packages/babel-preset-minify#option-groups). Some of them are grouped into a single option named `unsafe`. This option can help you identify it sooner if the bug is in one these plugins. | ||
7. Produce a minimal repro of the same issue - the function block containing the bug should be enough to help reproduce the bug. | ||
8. [Report it 🙂](https://github.com/babel/minify/issues/new) | ||
9. You're awesome. Thanks! | ||
|
||
### Releasing | ||
|
||
> If you are releasing a new package, you'll want to run `./scripts/npm-owner-update.sh` to add all owners to the new npm package after releasing. Or do it manually via `https://www.npmjs.com/package/package-name-here/access`. | ||
If you need to update deps run `npm run clean` and then `npm run bootstrap`. | ||
|
||
To get the changelog, run `npm run changelog` to print to the terminal. | ||
|
||
Use `npm run publish`. It will run `lerna publish` (we use `--independent`) so it will prompt the version number for every package. | ||
When you feel ready to jump into babel-minify source code, a good place to start is to look for issues tagged with [help wanted](https://github.com/babel/minify/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) and/or [good first issue](https://github.com/babel/minify/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
# Developing babel-minify | ||
|
||
Note: These are docs about contributing to the project. The documentation for plugins, presets, helpers, CLI and other packages are found in the respective package directory's README. | ||
|
||
The project structure is a [monorepo](https://github.com/babel/babel/blob/master/doc/design/monorepo.md) same as the one followed in the [babel](https://github.com/babel/babel) project. Read more about this structure in [babel's monorepo design documentation](https://github.com/babel/babel/blob/master/doc/design/monorepo.md). | ||
|
||
## Table of Contents | ||
|
||
1. [Installation, build and run](setup.md) | ||
1. [Linting and Testing](tests.md) | ||
1. [Benchmark Scripts](benchmarks.md) | ||
1. [Debugging Tips](debugging.md) | ||
1. [Releasing packages](releasing.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
# Benchmarks | ||
|
||
## Comparision with other minifiers | ||
|
||
[benchmark.js](https://github.com/babel/minify/blob/master/scripts/benchmark.js) compares BabelMinify with [Uglify](https://github.com/mishoo/UglifyJS2), [Closure Compiler](https://github.com/google/closure-compiler) and [Closure Compiler JS](https://github.com/google/closure-compiler-js) | ||
|
||
```sh | ||
./scripts/benchmark.js [file...] | ||
``` | ||
|
||
## Compare plugins - time | ||
|
||
[plugin-timing.js](https://github.com/babel/minify/blob/master/scripts/plugin-timing.js) is used to calculate and compare the time spent in each plugin. | ||
|
||
```sh | ||
./scripts/plugin-timing.js file.js | ||
``` | ||
|
||
## Compare plugins - size | ||
|
||
[plugin-contribution.js](https://github.com/babel/minify/blob/master/scripts/plugin-contribution.js) calculates how much each plugin of babel-minify contributes to size reduction. | ||
|
||
```sh | ||
./scripts/plugin-contribution.js file.js | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
# Debugging | ||
|
||
In your project, if you find that there is a bug that appears ONLY when you use BabelMinify, it's most likely that there is a bug in BabelMinify and you should definitely report it. Here are some guidelines that might help you drill down the issue. If it doesn't help you, you can of course create a minimal repro project with the bug and report it. | ||
|
||
## Compile time Errors | ||
|
||
If you get a syntax error at compile time, then it could be a few things: | ||
|
||
1. The code is actually invalid syntax. | ||
1. You didn't turn on the relevant Babel plugin for that syntax (if experimental). | ||
1. The parser itself doesn't handle the syntax being used (a [babylon](https://github.com/babel/babel/tree/master/packages/babylon) bug). | ||
|
||
If the syntax error occurs at runtime, it likely means the code generator ([babel-generator](https://github.com/babel/babel/tree/master/packages/babel-generator)) has a bug and has output invalid code. | ||
|
||
## Runtime errors | ||
|
||
When you run your minified code in the browser, | ||
|
||
1. If there is an error in the console, as a first step, look around the code block where the error happens, and the code block of a few steps up in the stack. | ||
1. Try to predict what caused the error and try relating it to some of the plugin names in the [packages/](https://github.com/babel/minify/tree/master/packages) directory. The major ones (that do a lot of transformations) are - mangle, deadcode-elimination and simplify. | ||
1. Every plugin that Babel-Minify uses has an option in preset to toggle it on/off - [preset-options](https://github.com/babel/minify/tree/master/packages/babel-preset-minify#options) | ||
1. Disable any transformation(s) that you suspect are causing problems. Turning OFF mangling (`mangle: false`) is a good practice if you don't think it's related to a mangling bug, since unmangled variable names will make debugging easier. | ||
1. Sometimes it might NOT be a bug with one plugin but a combination of plugins. Again, `deadcode-elimination` and `simplify` maybe good candidates to start with here as they perform many transformations. | ||
1. Sometimes it might because of the [unsafe transformations](https://github.com/babel/minify/tree/master/packages/babel-preset-minify#option-groups). Some of them are grouped into a single option named `unsafe`. This option can help you identify it sooner if the bug is in one these plugins. | ||
1. Produce a minimal repro of the same issue - the function block containing the bug should be enough to help reproduce the bug. | ||
1. [Report it 🙂](https://github.com/babel/minify/issues/new) | ||
1. You're awesome. Thanks! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
# Releasing | ||
|
||
> If you are releasing a new package, you'll want to run `./scripts/npm-owner-update.sh` to add all owners to the new npm package after releasing. Or do it manually via `https://www.npmjs.com/package/package-name-here/access`. | ||
If you need to update deps run `npm run clean` and then `npm run bootstrap`. | ||
|
||
To get the changelog, run `npm run changelog` to print to the terminal. | ||
|
||
Use `npm run publish`. It will run `lerna publish` (we use `--independent`) so it will prompt the version number for every package. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,45 @@ | ||
# Setup | ||
|
||
## Requirements | ||
|
||
+ node >= 4 | ||
+ [yarn](https://yarnpkg.com) >= 1.0.0 (with yarn workspaces support) | ||
|
||
## Clone | ||
|
||
```sh | ||
git clone https://github.com/babel/minify | ||
cd minify | ||
``` | ||
|
||
## Install Dependencies | ||
|
||
```sh | ||
yarn | ||
``` | ||
|
||
## Build | ||
|
||
To build **once**: | ||
|
||
```sh | ||
yarn build | ||
``` | ||
|
||
Or to do an incremental build in watch mode: | ||
|
||
```sh | ||
yarn watch | ||
``` | ||
|
||
## Use babel-minify's master branch in your project | ||
|
||
If you're using the preset - link the preset package ([babel-preset-minify](../packages/babel-preset-minify)). If you're using the [CLI](../packages/babel-minify) or [babel-minify NodeAPI](../packages/babel-minify) or the [gulp plugin](../packages/gulp-babel-minify), link the relevant package to your project. | ||
|
||
```sh | ||
cd packages/babel-preset-minify | ||
yarn link | ||
|
||
cd /path/to/your-project | ||
yarn link babel-preset-minify | ||
``` |
Oops, something went wrong.