Contributing

Since sandglass is an open-source project, it is always looking for contributors. Below, you’ll find how to get started on sandglass development and what rules we’d like you to follow, if you wish to contribute code.

Community

The primary way of getting in touch with the sandglass developers is through our mailing list hosted at google groups.

Also, you may want to follow @fabianbuechler, @jeronimoalbi or @krampf on Twitter.

Quickstart

If you would like to contribute to sandglass just follow these quidelines:

  1. Sandglass is hosted on bitbucket at https://bitbucket.org/fabianbuechler/sandglass/
  2. Create a fork, add your changes there.
  3. Send a pull request whenever you feel your code is ready.

Detailed Contribution Process

Contributing Bug-Reports

Bug reports, and of course feature requests, are highly welcome, since they help us to improve the quality of sandglass.

Please use our issuetracker on bitbucket for both alike.

Contributing Code

If you would like to see a new feature in sandglass, please discuss it on our mailinglist up front so that we don’t waste your time by not merging your contribution.

  • Any code will be reviewed and tested by at least one core developer. Of course, everyone is welcome to give feedback.
  • Code must be tested. Please provide unit-tests for bugfixes and new features alike.
  • Documentation should be adapted to your changes, if relevant. New features of course need new documentation.

Syntax conventions

  • For Python code, we try to conform to PEP8 standard. Please use the pep8 command installed with the development requirements (outlined in Setting up a Development Environment) to check for compliance.
  • For all other code (HTML, CSS, JS and reStructuredText for documentation) we try at least to follow some rules like:
    • 4 spaces indentation, except for reStructuredText where sometimes 4 just does not work.
    • Lines should be 79 characters maximum, except for HTML.

In general, take a look at existing code and try to stick to the conventions you can easily spot there.

Contributing Tests

Tests are essential. Having a comprehensive suite of unit-test and integration tests is most important to us. Contributing good tests earns you extra respect.

In general, tests should be:

  • Unitary, if possible. Test only one function/method/class.
  • Fast. Just make sure your test does not double the time to run the test-suite for everyone else.

Where Tests should go

  • Application-specific (speaking of Django apps) tests should go into the tests module of the respective application.

    That applies to all sandglass.* apps that are found in the INSTALLED_APPS setting.

  • Project-specific tests should go to the pseudo-app tests in the repository root.

    For example, that also applies to tests for the sandglass.lib module.

Running the Tests

To run all our tests you need to install tox, change to the repository’s root directory, where the tox.ini is located, and invoke the tox command:

$ sudo pip install tox
$ cd path/to/sandglass/code
$ tox

Hint

Since tox runs tests with multiple interpreters, you should not have any virtualenv activated.

This will automatically run the tests in Python 2.6 and 2.7. Also, the documentations (for users and developers) and test-coverage reports will be generated and the Python code will be checked for pep8 compliance.

If you want to run the tests for a specific environment only, pass the -e option to tox:

$ tox -e py27
# or
$ tox -e docs

To run only a certain test, you can also invoke tox like this:

$ tox -e py27 -- tests.SomeUnitTestClass.test_something

Test Coverage

The py27 test environment automatically generates coverage reports. Thus, to generate the reports, you only need to invoke tox or tox -e py27.

This generates HTML reports in the /docs/_coverage/ directory.

Contributing Documentation

Documentation is often considered to be even more important than the code itself. So, contributing docs — just like tests — earns you extra respect.

Please stick to the following rules:

  • We use Sphinx and thus reStructuredText, so that’s what you should use.
  • Everything should be written in plain English.
  • Not making any assumptions about the readers. Link to external documentation (for libraries, etc.) and explain even the obvious.

Building the Documentation

If you have Sphinx installed in your virtualenv, you can build the documentation by changing to the respective directory and using the make command:

(sandglass)$ cd path/to/sandglass/code/
(sandglass)$ cd docs/
(sandglass)$ make clean
(sandglass)$ make html

Also, as outlined in Running the Tests, you can use tox to build the documentation:

$ cd path/to/sandglass/code/
$ tox -e docs