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/Kinto/kinto.js
$ cd kinto.js
$ npm install
Notes
Tagged versions are also available from npm, though cloning the repository is the prefered way for contributing code.
Tests
In order to run the tests, you'll need:
- to have Python available on your system;
- to install Kinto locally;
- 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 when source files change and rerun the tests each time they do:
$ npm run tdd
Note that it won't perform code coverage analysis.
You can also 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 explictly 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, with the current version in the filename (for instance, 2.0.1
):
dist/kinto.js
: Development version, unminified, embedding source maps;dist/kinto.min.js
: Production version, minified, no source maps;dist/kinto.noshim.js
: Production version, minified, no polyfills;dist/moz-kinto-offline-client.js
: Firefox internal component bundle (for Mozilla specific use).
Once a new version is packaged and published to npm, the unpkg makes ready-to-use kinto.js assets available from the following urls:
- http://unpkg.com/kinto/dist/kinto.js for the development version;
- http://unpkg.com/kinto/dist/kinto.min.js for the production version.
- http://unpkg.com/kinto/dist/kinto.noshim.js for the production version without polyfills.
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
Generating browsable API docs
API docs are available online.
To generate them locally:
$ esdoc -c esdoc.json && open esdoc/index.html
Publication is done manually by submitting new versions to doc.esdoc.org.
Publishing to npm
$ npm run publish-package
Running a local demo server
Run this command:
$ npm run demo
Then point your browser at http://localhost:8080/
Publishing the demo
The demo is hosted on Gihub pages; to publish the current demo version:
$ npm run publish-demo