How to contribute to Kuzzle
Here are a few rules and guidelines to follow if you want to contribute to Kuzzle and, more importantly, if you want to see your pull requests accepted by Kuzzle team.
We use most of the NPM Coding Style rules, except for these ones:
- Semicolons at the end of lines
- 'Comma first' rule is not followed
- Prefer async/await or promises instead of callbacks as often as you can
- Except for methods invoked before the funnel module: ALWAYS use callbacks there to prevent event loop saturation (i.e. mostly methods handling network connections)
- Always add/update the corresponding unit and/or functional tests. We won't accept non-tested pull requests.
- Documentation and comments are more important than code: comment your code, use jsdoc for every new function, add or update markdown documentation if need be. We won't accept undocumented pull requests.
- Similar to the previous rule: documentation is important, but also is code readability. Write self-describing code.
General rules and principles we'd like you to follow
- If you plan to add new features to Kuzzle, make sure that this is for a general improvement to benefit a majority of Kuzzle users. If not, consider making a plugin instead (check our plugin documentation)
- Follow the KISS Principle
- Follow The Boy Scout Rule
For development only, we built a specific docker-compose file:
docker-compose.yml. You can use it to profile, debug, test a variable on the fly, add breakpoints and so on, thanks to chrome-devtools.
Check the logs at the start of Kuzzle using the development docker image to get the appropriate debug URL.
How to run the development stack (needs Docker 1.10+ and Docker Compose 1.8+):
# clone this repository git clone firstname.lastname@example.org:kuzzleio/kuzzle.git cd kuzzle # Start a kuzzle cluster with development tools enabled docker-compose up
You can now access the Kuzzle HTTP/WebSocket API through the following URL:
This is the entrypoint for the loadbalancer: API requests are then forwarded to kuzzle individual kuzzle nodes (round-robin).
For development purposes, nodes can be accessed individually:
|Node no.||HTTP/WebSocket port||MQTT port||Chrome Inspect Port|
Everytime a modification is detected in the source files, the nodes are automatically restarted.
Kuzzle over SSL
The development stack include a endpoint to access Kuzzle API through SSL on port
The certificates are privately signed, using provided CA certificate.
You'll need to import the CA certificate to your browser and possibly your system local authorities to make it verified.
Once done, your browser should not complain when reaching https://localhost:7443.
The CA certificate is here: docker/nginx/kuzzleCA.crt
Using node.js, for instance when using the sdk, you'll need to pass the CA cert using the
NODE_EXTRA_CA_CERTS environment variable:
NODE_EXTRA_CA_CERTS=/path/to/certificate/kuzzleCA.crt wscat -c wss://localhost:7443
Create a plugin
See our plugins documentation
Using docker, with Kuzzle running in Docker
$ docker-compose up -d # Wait for Kuzzle stack to be up, and start the entire test suite (long) $ npm run test # To launch tests individually: # linter: check that the code is properly written $ npm run test:lint # unit tests: test parts of the code individually $ npm run test:unit # functional tests: test Kuzzle's API behavior $ npm run test:functional