1 | # Contributing
|
2 |
|
3 | ## Adding a new plugin or polyfill to support (when approved in the next ECMAScript version)
|
4 |
|
5 | ### Update [`plugin-features.js`](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugin-features.js)
|
6 |
|
7 | *Example:*
|
8 |
|
9 | If you were going to add `**` which is in ES2016:
|
10 |
|
11 | Find the relevant entries on [compat-table](https://kangax.github.io/compat-table/es2016plus/#test-exponentiation_(**)_operator):
|
12 |
|
13 | `exponentiation (**) operator`
|
14 |
|
15 | Find the corresponding babel plugin:
|
16 |
|
17 | `@babel/plugin-transform-exponentiation-operator`
|
18 |
|
19 | And add them in this structure:
|
20 |
|
21 | ```js
|
22 | // es2016
|
23 | "@babel/plugin-transform-exponentiation-operator": {
|
24 | features: [
|
25 | "exponentiation (**) operator",
|
26 | ],
|
27 | },
|
28 | ```
|
29 |
|
30 | ### Update data for `core-js@2` polyfilling
|
31 |
|
32 | *Example:*
|
33 |
|
34 | In case you want to add `Object.values` which is in ES2017:
|
35 |
|
36 | Find the relevant feature and subfeature on [compat-table](https://kangax.github.io/compat-table/es2016plus/#test-Object_static_methods_Object.values)
|
37 | and split it with `/`:
|
38 |
|
39 | `Object static methods / Object.values`
|
40 |
|
41 | Find the corresponding module on [`core-js@2`](https://github.com/zloirock/core-js/tree/v2/modules):
|
42 |
|
43 | `es7.object.values.js`
|
44 |
|
45 | Find required ES version in [`corejs2-built-in-features.js`](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/corejs2-built-in-features.js) and add the new feature:
|
46 |
|
47 | ```js
|
48 | const es = {
|
49 | //...
|
50 | "es7.object.values": "Object static methods / Object.values"
|
51 | }
|
52 | ```
|
53 |
|
54 | If you wan to transform a new built-in by `useBuiltIns: 'usage'`, add mapping to related `core-js` modules to [this file](https://github.com/babel/babel/blob/master/packages/babel-preset-env/polyfills/corejs2/built-in-definitions.js).
|
55 |
|
56 | ### Update data for `core-js@3` polyfilling
|
57 |
|
58 | Just update the version of [`core-js-compat`](https://github.com/zloirock/core-js/tree/master/packages/core-js-compat) in dependencies.
|
59 |
|
60 | If you wan to transform a new built-in by `useBuiltIns: 'usage'`, add mapping to related [`core-js`](https://github.com/zloirock/core-js/tree/master/packages/core-js/modules) modules to [this file](https://github.com/babel/babel/blob/master/packages/babel-preset-env/polyfills/corejs3/built-in-definitions.js).
|
61 |
|
62 | If you want to mark a new proposal as shipped, add it to [this list](https://github.com/babel/babel/blob/master/packages/babel-preset-env/polyfills/corejs3/shipped-proposals.js).
|
63 |
|
64 | ### Update [`plugins.json`](https://github.com/babel/babel/blob/master/packages/babel-preset-env/data/plugins.json)
|
65 |
|
66 | Until `compat-table` is a standalone npm module for data we are using the git url
|
67 |
|
68 | `"compat-table": "kangax/compat-table#[latest-commit-hash]"`,
|
69 |
|
70 | So we update and then run `npm run build-data`. If there are no changes, then `plugins.json` will be the same.
|
71 |
|
72 | ## Tests
|
73 |
|
74 | ### Running tests locally
|
75 |
|
76 | ```bash
|
77 | npm test
|
78 | ```
|
79 |
|
80 | ### Checking code coverage locally
|
81 |
|
82 | ```bash
|
83 | npm run coverage
|
84 | ```
|
85 |
|
86 | ### Writing tests
|
87 |
|
88 | #### General
|
89 |
|
90 | All the tests for `@babel/preset-env` exist in the `test/fixtures` folder. The
|
91 | test setup and conventions are exactly the same as testing a Babel plugin, so
|
92 | please read our [documentation on writing tests](https://github.com/babel/babel/blob/master/CONTRIBUTING.md#babel-plugin-x).
|
93 |
|
94 | #### Testing the `debug` option
|
95 |
|
96 | Testing debug output to `stdout` is similar. Under the `test/debug-fixtures`,
|
97 | create a folder with a descriptive name of your test, and add the following:
|
98 |
|
99 | * Add a `options.json` file (just as the other tests, this is essentially a
|
100 | `.babelrc`) with the desired test configuration (required)
|
101 | * Add a `stdout.txt` file with the expected debug output. For added
|
102 | convenience, if there is no `stdout.txt` present, the test runner will
|
103 | generate one for you.
|