Contribution

If you like to contribute to this project please read the following guides and read the internals sections for Server and Client code.

Django Code

To install all requirements for development and testing, you can use the provided requirements file.

$ pip install -e .[tests]

Testing the code

django-omnibus uses py.test for testing. Please ensure that all tests pass before you submit a pull request. py.test also runs PEP8 and PyFlakes checks on every run.

This is how you execute the tests and checks from the repository root directory.

$ py.test

If you want to generate a coverage report, you can use the following command.

$ py.test --cov=omnibus --cov-report=html .

Documentation

django-omnibus uses Sphinx for documentation. You find all the sources files in the docs/source folder.

To update/generate the html output of the documentation, use the following command inside the docs folder.

$ make html

Please make sure that you don’t commit the build files inside docs/build.

JavaScript Code

The client side development depends on the GruntJS Taskrunner. If you haven’t used grunt before, be sure to check out the Getting Started guide.

To setup your local environment call npm install in the projects root. This downloads all necessary dependencies to run the taskrunner.

Change the code

A build of the JavaScript library will be made on each new release.

The release is based on the AMD Modules located in the source directory “src” inside the “static” folder. For these circumstances it’s not meant to made changes in the JavaScript files outside the “src” folder, cause they are overwritten by the build output. If you wan’t to contribute to this project please commit only the src-files.

To run the build process you can call the grunt taskrunner using:

$ grunt

This starts validation, testing, building and documention processes in a row as default task of the taskrunner. The build process creates the library itself and a minified version of them, using the extention .min.js.

Generate a documentation

The client code is fully documented using JSDoc. To get an overview about the classes and functions generate your own JSDoc running the following command. The generated documentation will open immediately.

$ grunt doc

Validation & testing

Before you commit your code changes and offer a pull request run the following tasks via grunt:

To validate the code according our JSHint, JSCS and indentation rules run:

$ grunt validate

To finally test your JavaScript code run:

$ grunt test

The tests are written using Jasmine. The test specs are located at testing/jstests/.

Code declaration

The most JavaScript code will be validated as described above using JSHint and JSCS. But there are some rules which won’t be checked:

  • To declare a private property, add a leading underscore _ to the properties name, for example: _isValid: true.
  • To declare a constant, use uppercase letters and underscores like: THIS_IS_A_CONSTANT = 'value'.