Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
doc: Rewrite README.md and move build and contribution details into a…
… separate doc file (#147)
- Loading branch information
Showing
2 changed files
with
244 additions
and
21 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,106 @@ | ||
Hi! Thanks for your interest in helping to make the "cross-browser extension" developers life easier by contributing to the `webextension-polyfill` library. | ||
|
||
This document provides some additional information that you may find useful while looking at how to apply changes to this library and submit them for review. | ||
|
||
Table of contents | ||
================= | ||
|
||
* [Building](#building) | ||
* [Test Suites](#test-suites) | ||
* [Writing commit messages](#writing-commit-messages) | ||
|
||
## Building | ||
|
||
To build, assuming you've already installed [node >= 6](https://nodejs.org) and | ||
[npm](https://www.npmjs.com/), simply run: | ||
|
||
```sh | ||
git clone https://github.com/mozilla/webextension-polyfill.git | ||
|
||
cd webextension-polyfill | ||
|
||
npm install | ||
|
||
npm run test | ||
``` | ||
|
||
This will install all the npm dependencies and build both non-minified and minified versions | ||
of the final library, and output them to `dist/browser-polyfill.js` and `dist/browser-polyfill.min.js`, | ||
respectively, and finally execute the unit tests on the generated dist files. | ||
|
||
## Test Suites | ||
|
||
This project provides two test suites: | ||
|
||
- unit tests (which only require Node.js to run) | ||
- module bundlers smoke tests (which requires also browserify and webpack to be installed globally) | ||
- integration tests (which requires also a stable version of Chrome and Firefox) | ||
|
||
### Unit Tests | ||
|
||
The unit tests run in Node.js with [Mocha](https://mochajs.org), and use jsdom and | ||
[Sinon](https://sinonjs.org) to mock a browser-like environment for testing the library. | ||
|
||
The unit tests are located in the `"test/"` directory and they have to be named `"test/test-*.js"`. | ||
|
||
`npm run test` run all the unit tests on the non-minified version of the library, | ||
whereas `npm run test-minified` can be used to run the unit tests on the minified version. | ||
|
||
Optionally code coverage data can be collected and reported while running the unit tests, | ||
by running `npm run test-coverage`. | ||
|
||
### Module Bundler smoketests | ||
|
||
The shell script `test/run-module-bundlers-smoketests.sh` runs browserify and webpack, | ||
to verify that the most commonly used module bundlers are not raising any unexpected error | ||
while building a bundle that requires this library. | ||
|
||
### Integration Tests | ||
|
||
This repository also includes a small set of integration tests, located at `"test/integration/"`. | ||
The integration tests use selenium-webdriver to run a set of test extensions | ||
(located at `"test/fixtures/"`) on real browsers, currently Chrome (as the browser officially | ||
supported by this library) and Firefox (to compare the polyfilled APIs with the ones natively | ||
provided on Firefox). | ||
|
||
The shell script `test/run-browsers-smoketests.sh` (executed by the Travis CI service on every | ||
pull request) runs this test suite on both the browsers. | ||
|
||
To run the integration tests on a single browser: | ||
|
||
```sh | ||
TEST_BROWSER_TYPE=chrome npm run test-integration | ||
``` | ||
or | ||
|
||
```sh | ||
TEST_BROWSER_TYPE=firefox npm run test-integration | ||
``` | ||
|
||
These tests emit their results using the TAP protocol. To get a nicer output on the console | ||
you may want to pipe the results to `tap-nirvana`, e.g. | ||
|
||
```sh | ||
TEST_BROWSER_TYPE=chrome npm run test-integration | ./node_modules/.bin/tap-nirvana | ||
``` | ||
|
||
## Writing commit messages | ||
|
||
The subject of the pull requests and commit messages must adhere to the Angular style of | ||
[semantic messages](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#commits). | ||
This allows us to auto-generate a changelog without too much noise in it. | ||
Additionally, write the commit message in past tense so it will read | ||
naturally as a historic changelog. | ||
|
||
Examples: | ||
* `feat: Added newAmazingAPI namespace to the metadata` | ||
* `fix: newAmazingAPI.create should reject on errors` | ||
* `docs: Improved contributor docs` | ||
* `style: Added no-console linting, cleaned up code` | ||
* `refactor: Split out myHelperFunction` | ||
* `perf: Changed myHelperFunction to be 2x faster` | ||
* `test: Added more tests for newAmazingAPI` | ||
* `chore: Upgraded yargs to 3.x.x` | ||
|
||
If you want to use scopes then it would look more like: | ||
`test(integration): Added test extension for newAmazingAPI`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters