From dc525edf514e48adca2db2c862a59a5022574eb1 Mon Sep 17 00:00:00 2001 From: Kai Cataldo Date: Sat, 4 Jun 2016 12:26:31 -0400 Subject: [PATCH] Clean up language/consistency in CONTRIBUTING.md (#3517) --- CONTRIBUTING.md | 40 +++++++++++++++++++--------------------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c3c349b3ae..2befd93b76 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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