CONTRIBUTING.md
# Contributing
**Please make sure your PR includes both tests and documentation.**
## File organization
All code is written in next-generation JavaScript and transpiled using Babel, including tests. Source files are located in `src` and transpiled to `lib`, which is gitignored. `dist` is for browser builds, and is not ignored. Add-ons (modules that are not part of core) are located in `src/addons`.
Tests for a module should be placed in a `__tests__` subdirectory and named with a `-test.js` suffix. For example, the test suite for the module at `foo/bar.js` should be located at `foo/__tests__/bar-test.js`.
## Building
Babel is used for transpilation, but refrain from using any features that require an ES6 or above polyfill, as this will increase the bundled size of the library — e.g. async/await or symbols. This does not apply to tests, however, as they do not affect the bundle size.
To transpile the source files:
```
make js
```
(If it's the first time you're building the `lib` directory, or if you've just run the clean task, you should run `make fast-js` to transpile all the files at once. Subsequent builds should use `make js`.)
Browser builds, one uncompressed and one compressed, are built using webpack. These should only be built right before a new release, not on every commit. These are not recommended for actual use — use a module bundler like webpack or browserify instead. They exist primarily so we can keep an eye on the overall size of the library.
To build for the browser:
```
make browser
```
To transpile and build for browser:
```
make build
```
To clean all generated files
```
make clean
```
## Tests
To run the test suite:
```
make test
```
(As in the previous section, you should run `make fast-js` for the first run. You can chain make tasks on the command line like so: `make fast-js test`).
Tests are run on the transpiled code, not the source files. If you rename or delete a source file, make sure the transpiled file is also deleted. You can always run `make clean` to clear out all generated files.
Tests are written using mocha and chai. chai-as-promised and async/await should be used for testing asynchronous operations. A browser environment is provided for React tests via jsdom. Continuous integration tests are run on Travis CI.
## Documentation
New features or API changes should be documented. Docs are located in the `docs` folder. Refer to the docs [README](docs/README.md) for information on how to build the docs. Please do not commit changes `dist/docs` — I will add those before deploying to GitHub pages.
## Code style
Code is linted using ESLint and babel-eslint. Rules are located in `.eslintrc`. Even if linting passes, please do your best to maintain the existing code style.
Linting is always run before testing. To run the lint task separately:
```
make lint
```