139 lines
4.3 KiB
Markdown
139 lines
4.3 KiB
Markdown
# 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).
|
|
|
|
## Resources
|
|
|
|
Check out the [babel-handbook](https://github.com/thejameskyle/babel-handbook/blob/master/translations/en/plugin-handbook.md#asts) and [ASTExplorer](http://astexplorer.net/) for some info about contributing to this project regarding Abstract Syntax Trees (ASTs).
|
|
|
|
## Setup local env
|
|
|
|
> Install yarn beforehand: https://yarnpkg.com/en/docs/install
|
|
|
|
To start developing on Babylon you only need to install its dependencies:
|
|
|
|
```bash
|
|
git clone https://github.com/babel/babylon
|
|
cd babylon
|
|
yarn
|
|
```
|
|
|
|
## Tests
|
|
|
|
### Running tests locally
|
|
|
|
To run a build, tests and perform lint/flow checks:
|
|
|
|
```bash
|
|
yarn test
|
|
```
|
|
|
|
If you only want to run the tests:
|
|
|
|
```bash
|
|
yarn run test-only
|
|
```
|
|
|
|
Note, this does not actually run a build, so you may have to call `yarn run build` after
|
|
performing any changes.
|
|
|
|
### Running one test
|
|
|
|
To run only a single test, add `"only": true` to the `options.json` inside any test fixture folder (you may have to create the file if it doesn't exist).
|
|
For example, let's say we want to only run the test for the [`test/fixtures/comments/basic/shebang-import`](https://github.com/babel/babylon/tree/7.0/test/fixtures/comments/basic/shebang-import) fixture.
|
|
|
|
Add `"only": true` to its `options.json`:
|
|
|
|
```json
|
|
{
|
|
"sourceType": "module",
|
|
"only": true
|
|
}
|
|
```
|
|
|
|
Then, run the tests using the same command as before:
|
|
|
|
```bash
|
|
yarn run test-only
|
|
```
|
|
|
|
### Checking code coverage locally
|
|
|
|
To generate code coverage, be sure to set `BABEL_ENV=test` so that code is instrumented during
|
|
the rollup build.
|
|
|
|
```bash
|
|
BABEL_ENV=test yarn run build && yarn run test-coverage
|
|
```
|
|
|
|
### Writing tests
|
|
|
|
Writing tests for Babylon is very
|
|
[similar to Babel](https://github.com/babel/babel/blob/master/CONTRIBUTING.md#writing-tests).
|
|
Inside the `tests/fixtures` folder are categories/groupings of test fixtures (es2015, flow,
|
|
etc.). To add a test, create a folder under one of these groupings (or create a new one) with a
|
|
descriptive name, and add the following:
|
|
|
|
* Create an `actual.js` file that contains the code you want Babylon to parse.
|
|
|
|
* Add an `expected.json` file with the expected parser output. For added convenience, if
|
|
there is no `expected.json` present, the test runner will generate one for you.
|
|
|
|
## Cross repository changes
|
|
|
|
If you are making changes to Babylon which make it necessary to also change things in Babel
|
|
you will want to link both repositories together. This can be done by doing the following
|
|
(assuming you have both Babel and Babylon already checked out):
|
|
|
|
```bash
|
|
cd babylon/
|
|
yarn link
|
|
yarn run build
|
|
cd ../babel/
|
|
make bootstrap
|
|
yarn link babylon
|
|
cd packages/babel-core/
|
|
yarn link babylon
|
|
cd ../babel-template/
|
|
yarn link babylon
|
|
cd ../babel-traverse/
|
|
yarn link babylon
|
|
cd ../babel-generator/
|
|
yarn link babylon
|
|
cd ../babel-types/
|
|
yarn link babylon
|
|
cd ../..
|
|
make build
|
|
make test
|
|
```
|
|
|
|
From now on Babel will use your local checkout of Babylon for its tests.
|
|
|
|
## Creating a new plugin (`spec-new`)
|
|
|
|
> Example: https://github.com/babel/babylon/pull/541
|
|
|
|
- Create a new issue that describes the proposal (ex: [#538](https://github.com/babel/babylon/issues/538)). Include any relevant information like proposal repo/author, examples, parsing approaches, meeting notes, presentation slides, and more.
|
|
- The pull request should include:
|
|
- [ ] An update to the [#plugins](https://github.com/babel/babylon#plugins) part of the readme. Add a new entry to that list for the new plugin flag (and link to the proposal)
|
|
- [ ] If any new nodes or modifications need to be added to the AST, update [ast/spec.md](https://github.com/babel/babylon/blob/master/ast/spec.md)
|
|
- [ ] Make sure you use the `this.hasPlugin("plugin-name-here")` check so that your new plugin code only runs when that flag is turned on (not default behavior)
|
|
- [ ] Add failing/passing tests according to spec behavior
|
|
- [ ] Start working about the Babel transform itself!
|
|
|
|
## Publishing
|
|
|
|
```sh
|
|
# run lerna-changelog from global install and copy it
|
|
lerna-changelog
|
|
# create tag or specific one (ex: `npm version v7.0.0-beta.16`)
|
|
npm version patch
|
|
# push to github
|
|
git push --follow-tags
|
|
# publish (sometimes need `npm publish --tag=next`)
|
|
npm publish
|
|
# upload changelog to github releases, etc
|
|
```
|