Hacking on Kinto.js

Hacking on Kinto.js requires a working NodeJS v0.12x environment.

Installation

Source code is hosted on Github.

$ git clone https://github.com/mozilla-services/kinto.js
$ cd kinto.js
$ npm install

Notes

Tagged versions are also available from npm, though cloning the repository is the prefered way for hacking and contributing code.

Tests

In order to run the tests, you'll need:

  1. to have Python available on your system;
  2. to install Kinto locally;
  3. to export the location of the installed pserve accordingly.

The simplest way to install Kinto is to do so in a virtual environment and activate it:

$ virtualenv venv
$ ./venv/bin/pip install kinto
$ source ./venv/bin/activate

Then you can run the tests by running:

$ npm test

You can alternatively run the tests in a more explicit fashion by passing the KINTO_PSERVE_EXECUTABLE environment variable, which can be found in the virtual environment's bin directory:

$ KINTO_PSERVE_EXECUTABLE="`pwd`/venv/bin/pserve" npm run test

Alternative test commands are also available:

$ npm run test-nocover    # runs tests skipping code coverage
$ npm run test-cover      # runs tests, code coverage; doesn't send results
$ npm run test-cover-html # runs tests, code coverage and opens a fancy html report

Notes

Code coverage reports are also browseable on Coveralls.

TDD mode

This command will watch for changes on the js source files then rerun the tests:

$ npm run tdd

Note that it won't perform code coverage analysis.

You can also grep to run a subset of tests that way:

$ npm run tdd -- -g Api # only runs Api-related tests

Of course, as for npm test, you can explictely pass the pass to the Kinto server pserve executable to use to execute integration tests:

$ KINTO_PSERVE_EXECUTABLE="/path/to/venv/bin/pserve" npm run tdd

Generating dist files

$ npm run dist

This should have created the following assets:

  • dist/kinto.dev.js: Developement version, unminified, embedding source maps;
  • dist/kinto.min.js: Production version, minified, no source maps.

Updating docs

Docs are written in Markdown using mkdocs, and are hosted on readthedocs.

Document sources are versionned in the Kinto.js repository, under the docs/ directory. Updates are automatically deployed when pushed to origin/master. That means the docs site is automatically updated everytime a PR lands.

To build docs locally, ensure mkdocs is properly installed, then run:

$ mkdocs build --clean

To serve them over http locally so you can see your modifications in real time:

$ mkdocs serve

Publishing to npm

$ npm run publish-package