Use absolute paths in Babel's CONTRIBUTING.md (#5431)
This commit is contained in:
Aaron Ang
Brian Ng
parent
12eb25c06c
commit
911b71f2c6
@ -2,7 +2,7 @@
|
||||
|
||||
----
|
||||
|
||||
<p align="center">
|
||||
<p align="center" class="toc">
|
||||
<strong><a href="#setup">Setup</a></strong>
|
||||
|
|
||||
<strong><a href="#running-lintingtests">Running linting/tests</a></strong>
|
||||
@ -27,7 +27,7 @@ Contributions are always welcome, no matter how large or small.
|
||||
|
||||
- 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): The Babel AST [spec](https://github.com/babel/babylon/blob/master/ast/spec.md) is a bit different from [ESTree](https://github.com/estree/estree). The differences are listed [here](https://github.com/babel/babylon#output).
|
||||
- This repository's [`/doc`](/doc) directory for notes on Babel's internals
|
||||
- This repository's [`/doc`](https://github.com/babel/babel/tree/master/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
|
||||
- When you feel ready to finally jump into the babel source code a good start is to look out for issues which are labeled with [help-wanted](https://github.com/babel/babel/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) and/or [beginner-friendly](https://github.com/babel/babel/issues?q=is%3Aissue+is%3Aopen+label%3A%22beginner-friendly%22).
|
||||
@ -47,7 +47,7 @@ You can check this with `node -v` and `npm -v`.
|
||||
In addition, make sure that Yarn is installed.
|
||||
Installation instructions can be found here: https://yarnpkg.com/en/docs/install.
|
||||
|
||||
#### Setup
|
||||
### Setup
|
||||
|
||||
```sh
|
||||
$ git clone https://github.com/babel/babel
|
||||
@ -77,7 +77,7 @@ If you wish to build a copy of Babel for distribution, then run:
|
||||
$ make build-dist
|
||||
```
|
||||
|
||||
#### Running linting/tests
|
||||
### Running linting/tests
|
||||
|
||||
You can run lint via:
|
||||
|
||||
@ -108,7 +108,7 @@ $ make test-only
|
||||
|
||||
Most likely you'll want to focus in on a specific issue.
|
||||
|
||||
To run tests for a specific package in [packages](/packages), you can use the `TEST_ONLY` environment variable:
|
||||
To run tests for a specific package in [packages](https://github.com/babel/babel/tree/master/packages), you can use the `TEST_ONLY` environment variable:
|
||||
|
||||
```sh
|
||||
$ TEST_ONLY=babel-cli make test
|
||||
@ -133,27 +133,27 @@ $ BABEL_ENV=cov make build
|
||||
$ ./scripts/test-cov.sh
|
||||
```
|
||||
|
||||
#### Writing tests
|
||||
### Writing tests
|
||||
|
||||
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).
|
||||
Most packages in [`/packages`](https://github.com/babel/babel/tree/master/packages) have a `test` folder, however some tests might be in other packages or in [`/packages/babel-core`](https://github.com/babel/babel/tree/master/packages/babel-core/test/fixtures).
|
||||
|
||||
##### `babel-plugin-x`
|
||||
#### `babel-plugin-x`
|
||||
|
||||
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`](https://github.com/babel/babel/tree/master/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) file whose function is similar to a `.babelrc` file, allowing you to pass in the plugins and settings you need for your tests.
|
||||
- There is an `index.js` file. It imports our [test helper](https://github.com/babel/babel/tree/master/packages/babel-helper-plugin-test-runner). (You don't have to worry about this).
|
||||
- There can be multiple folders under [`/fixtures`](https://github.com/babel/babel/tree/master/packages/babel-plugin-transform-exponentiation-operator/test/fixtures)
|
||||
- There is an [`options.json`](https://github.com/babel/babel/blob/master/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 have an `options.json` with different options in each subfolder.
|
||||
|
||||
- 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 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`](https://github.com/babel/babel/blob/master/packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/binary/actual.js) file and an [`expected.js`](https://github.com/babel/babel/blob/master/packages/babel-plugin-transform-exponentiation-operator/test/fixtures/exponentian-operator/binary/expected.js) file.
|
||||
- If you need to expect an error, you can ignore creating the `expected.js` file and pass a new `throws` key to the `options.json` that contains the error string that is created.
|
||||
- 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.
|
||||
- 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`](https://github.com/babel/babel/blob/master/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`.
|
||||
|
||||
@ -186,7 +186,7 @@ If you need to check for an error that is thrown you can add to the `options.jso
|
||||
}
|
||||
```
|
||||
|
||||
##### Bootstrapping expected output
|
||||
#### Bootstrapping expected output
|
||||
|
||||
For both `babel-plugin-x` and `babylon`, you can easily generate an `expected.js`/`expected.json` automatically by just providing `actual.js` and running the tests as you usually would.
|
||||
|
||||
@ -202,7 +202,7 @@ For both `babel-plugin-x` and `babylon`, you can easily generate an `expected.js
|
||||
- expected.json (will be generated if not created)
|
||||
```
|
||||
|
||||
#### Debugging code
|
||||
### Debugging code
|
||||
|
||||
A common approach to debugging JavaScript code is to walk through the code using the [Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools/) debugger.
|
||||
For illustration purposes, we are going to assume that we need to get a better understanding of [`Generator.generate()`](https://github.com/babel/babel/blob/b5246994b57f06af871be6a63dcc4c6fd41d94d6/packages/babel-generator/src/index.js#L32), which is responsible for generating code for a given AST.
|
||||
@ -239,9 +239,9 @@ The debugger starts at the first executed line of code, which is Mocha's first l
|
||||
Click _Resume script execution_ <img src="https://i.imgur.com/TmYBn9d.png" alt="Resume script execution button." width="16"> to jump to the set breakpoint.
|
||||
Note that the code shown in Chrome DevTools is compiled code and therefore differs.
|
||||
|
||||
#### Internals
|
||||
## Internals
|
||||
- AST spec ([babylon/ast/spec.md](https://github.com/babel/babylon/blob/master/ast/spec.md))
|
||||
- Versioning ([doc/design/versioning.md](./doc/design/versioning.md))
|
||||
- Monorepo ([doc/design/monorepo.md](./doc/design/monorepo.md))
|
||||
- Compiler environment support ([doc/design/compiler-environment-support.md](./doc/design/compiler-environment-support.md))
|
||||
- Compiler assumptions ([doc/design/compiler-assumptions.md](./doc/design/compiler-assumptions.md))
|
||||
- Versioning ([doc/design/versioning.md](https://github.com/babel/babel/blob/master/doc/design/versioning.md)
|
||||
- Monorepo ([doc/design/monorepo.md](https://github.com/babel/babel/blob/master/doc/design/monorepo.md))
|
||||
- Compiler environment support ([doc/design/compiler-environment-support.md](https://github.com/babel/babel/blob/master/doc/design/compiler-environment-support.md))
|
||||
- Compiler assumptions ([doc/design/compiler-assumptions.md](https://github.com/babel/babel/blob/master/doc/design/compiler-assumptions.md))
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user