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.
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.
If you would like to contribute to sandglass just follow these quidelines:
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.
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.
In general, take a look at existing code and try to stick to the conventions you can easily spot there.
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:
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.
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
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.
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:
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