If you want to improve Watai, this document will guide you through the necessary environment and provided helpers.
But first of all, thanks for wanting to contribute! :)
Simply fork the project and clone the repository on your machine, and install the developer dependencies.
cd path/to/watai/clone
npm install --no-shrinkwrapPlease read the Code conventions prior to coding. An editorconfig file is provided, as well as an automated style checker.
Build processes are mostly automated through npm scripts.
Most are documented here, and you can get a full list by running npm run.
Test runner: Mocha.
npm test
You can execute a subset of tests only if you're working on a specific part. For example, considering you're adding tests to controllers:
[node_modules/.bin/]mocha test [--watch] test/unit/controller
Coverage information is provided by Istanbul. It is always output after tests. You can check the thresholds with:
npm run test-coverage
Since Watai's integration tests (exit codes checks, CLI options) are long and little prone to fail suddenly, they are not executed in the default test command.
To execute all tests, including the longer ones, to ensure no regression was made, use the following command:
npm run test-exhaustive
Documentation generator and syntax: JSdoc.
npm run doc
You will find the generated documentation as HTML files in the doc/api folder. Open doc/api/index.html to start.
If you're hacking on the core of Watai rather than a plugin, you can use:
npm run doc-private
Please update the Changelog.md at the root of the project for every change you bring.
Remember we use SemVer.
If you ever update or add a module, you will need to update the NPM shrinkwrap file to lock down dependencies versions (Ruby folks, this is the same as a Gemfile.lock).
To do so, simply cd to your Watai clone and type:
npm shrinkwrap
However, when committing, you will notice in the diff that many dependencies are added, not only the ones you added yourself. These are the developer dependencies, and should never be committed. Discard the hunk before committing the npm-shrinkwrap.json file.
Once your changes are ready, i.e. you made sure:
- You didn't break anything, tested properly, and respected the styleguide (
npm run test-exhaustive). - You cleanly documented the new code (
npm run doc-private).
…you may open a pull request to ask your new code to be merged in the baseline.
Please make sure the reason why you made these changes is clear in the pull request comments, and please reference any linked issue in these same comments.
Your pull request will then be reviewed, and eventually added to the mainline. Thanks for helping to improve Watai! :)
We use Semantic Versioning to convey compatibility information through version numbers. If merged changes in master impact the end user in any way, the version number should be updated as specified by SemVer.
To ensure quality, we use field testing before publishing official versions. Thus, when the version number is updated, it should be sufficed by -alpha or -beta upon merge, with a numeric indicator incremented on each later merge. The switch from alpha to beta happens on feature freeze, decided by the maintainers. The switch from beta to official release happens after 2 weeks without issues.
This means there could be a time within which both a beta and an alpha for the next version are both available.
master is always the edge version. You can access stable versions through tags, as listed in the Releases tab. Unstable versions are distributed under the edge NPM tag.
npm version # remember to use semver.org
npm publish
npm packCopy the changelog entries and upload the resulting pack to the Releases tab of GitHub.