cerxes/babel
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Clean up language/consistency in CONTRIBUTING.md (#3517)

Browse Source
This commit is contained in:
Kai Cataldo
2016-06-04 12:26:31 -04:00
committed by Henry Zhu
parent 61b3a6314b
commit dc525edf51
1 changed files with 19 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
CONTRIBUTING.md
View File

@@ -17,16 +17,15 @@
# Contributing
Contributions are always welcome, no matter how large or small. Before
contributing, please read the
[code of conduct](https://github.com/babel/babel/blob/master/CODE_OF_CONDUCT.md).
contributing, please read our [code of conduct](https://github.com/babel/babel/blob/master/CODE_OF_CONDUCT.md).
## Not sure where to start?
- If you aren't just making a documentation change, you'll probably want to learn a bit about a few topics.
- [ASTs](https://en.wikipedia.org/wiki/Abstract_syntax_tree) (Abstract Syntax Tree): Our current [spec](https://github.com/babel/babel/tree/master/doc/ast) is a bit different from [ESTree](https://github.com/estree/estree).
- [`/doc`](/doc) for notes on babel internals
- Check out [the babel plugin handbook](https://github.com/thejameskyle/babel-handbook/blob/master/translations/en/plugin-handbook.md#babel-plugin-handbook). Core babel plugins are written the same way as any other plugin!
- Checkout [AST Explorer](http://astexplorer.net/#/scUfOmVOG5) to learn more about ASTs or making your own plugin live
- This repository's [`/doc`](/doc) directory for notes on Babel's internals
- Check out [the Babel Plugin Handbook](https://github.com/thejameskyle/babel-handbook/blob/master/translations/en/plugin-handbook.md#babel-plugin-handbook) - core plugins are written the same way as any other plugin!
- Check out [AST Explorer](http://astexplorer.net/#/scUfOmVOG5) to learn more about ASTs or make your own plugin in the browser
> If you're stuck, feel free to check out the `#development` channel on our [slack](https://slack.babeljs.io).
@@ -54,9 +53,9 @@ to build Babel **once** or:
$ make watch
```
to have Babel build itself then incrementally build files on change.
to have Babel build itself and incrementally build files on change.
If you wish to build a copy of Babel for distribution then run:
If you wish to build a copy of Babel for distribution, then run:
```sh
$ make build-dist
@@ -72,7 +71,7 @@ You can run tests for all packages via:
$ make test
```
This is mostly overkill and you can limit the package to a select by using the `TEST_ONLY` environment variable:
To run tests for a specific package, you can use the `TEST_ONLY` environment variable:
```sh
$ TEST_ONLY=babel-cli make test
@@ -92,25 +91,24 @@ $ make test-cov
#### Writing tests
Most packages in [`/packages`](/packages) have a `test` folder.
Some tests might be in different packages or in [`/packages/babel-core`](/packages/babel-core/test/fixtures).
Most packages in [`/packages`](/packages) have a `test` folder, however some tests might be in other packages or in [`/packages/babel-core`](/packages/babel-core/test/fixtures).
##### `babel-plugin-x`
All the babel plugins (and other packages) that have a `/test/fixtures` are written in a similar way.
All the Babel plugins (and other packages) that have a `/test/fixtures` are written in a similar way.
For example in [`babel-plugin-transform-exponentiation-operator/test`](/packages/babel-plugin-transform-exponentiation-operator/test)
For example, in [`babel-plugin-transform-exponentiation-operator/test`](/packages/babel-plugin-transform-exponentiation-operator/test):
- There is an `index.js` file. It imports our [test helper](/packages/babel-helper-plugin-test-runner). (You don't have to worry about this).
- There can be multiple folders under [`/fixtures`](/packages/babel-plugin-transform-exponentiation-operator/test/fixtures)
- There is an [`options.json`](/packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/options.json) is basically a `.babelrc` file to pass in the plugins and settings you need for your tests.
- There is an [`options.json`](/packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/options.json) file whose function is similar to a `.babelrc` file, allowing you to pass in the plugins and settings you need for your tests.
- For this test, we only need the relevant plugin, so it's just `{ "plugins": ["transform-exponentiation-operator"] }`.
- If necessary, you can specify a different `options.json` for each sub folder if you need different options.
- If necessary, you can have an `options.json` with different options in each subfolder.
- In each sub-folder, you can actually write out your different categories of tests. (You can name this by the feature you are testing, or you can reference the issue number)
- There are mainly two kinds of tests for plugins.
- One is a simple test of input/output by Babel. We do this by creating an [`actual.js`](packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/binary/actual.js) (the code before transformation) and [`expected.js`](/packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/binary/expected.js).
- The other type is a test to actually evaluate code an assert certain properties are true or not (this is usually better). We do this by creating an [`exec.js`](/packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/comprehensive/exec.js).
- In each subfolder, you can organize your directory structure by categories of tests. (Example: these folders can be named after the feature you are testing or can reference the issue number they fix)
- Generally, there are two kinds of tests for plugins
- The first is a simple test of the input and output produced by running Babel on some code. We do this by creating an [`actual.js`](packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/binary/actual.js) file and an [`expected.js`](/packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/binary/expected.js) file.
- The second and preferred type is a test that actually evaluates the produced code and asserts that certain properties are true or false. We do this by creating an [`exec.js`](/packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/comprehensive/exec.js) file.
In an actual/expected test, you simply write out the code you want transformed in `actual.js`.
@@ -125,17 +123,17 @@ and the expected output after transforming it with your `options.json` in `expec
// expected.js
Math.pow(2, 2);
```
In an `exec.js` test, we might want to actually run/check the code does what it's supposed to do rather than just check output.
In an `exec.js` test, we run or check that the code actually does what it's supposed to do rather than just check the static output.
```js
// exec.js
assert.equal(8, 2 ** 3);
assert.equal(24, 3 * 2 ** 3);
```
##### `babylon`
For `babylon` specifically, you can easily generate an `expected.json` automatically by just providing the `actual.js` and running `make test-only` like normal.
For `babylon` specifically, you can easily generate an `expected.json` automatically by just providing the `actual.js` and running `make test-only` as you usually would.
```
// Example