.. _contributing: ============== 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. .. _contributing-community: 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. .. _mailing list: http://groups.google.com/group/sandglass .. _@fabianbuechler: http://twitter.com/fabianbuechler .. _@jeronimoalbi: http://twitter.com/jeronimoalbi .. _@krampf: http://www.eintauchen.net/@krampf/ .. _contributing-quickstart: Quickstart ========== If you would like to contribute to sandglass just follow these quidelines: #. Sandglass is hosted on `bitbucket`_ at https://bitbucket.org/fabianbuechler/sandglass/ #. Create a fork, add your changes there. #. Send a pull request whenever you feel your code is ready. .. _bitbucket: http://bitbucket.org/ .. _contributing-setup: .. _contributing-process: Detailed Contribution Process ============================= .. _contributing-process-bugs: 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. .. _issuetracker on bitbucket: https://bitbucket.org/fabianbuechler/sandglass/issues .. _contributing-process-code: 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 :ref:`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. .. _contributing-process-syntax: Syntax conventions ^^^^^^^^^^^^^^^^^^ * For Python code, we try to conform to `PEP8 standard`_. Please use the ``pep8`` command installed with the development requirements (outlined in :ref:`contributing-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. .. _PEP8 standard: http://www.python.org/dev/peps/pep-0008/ .. _contributing-process-tests: 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. .. _contributing-process-tests-where: 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. .. _contributing-process-tests-running: 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: .. code-block:: bash $ 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 :ref:`test-coverage reports ` will be generated and the Python code will be :ref:`checked for pep8 compliance `. If you want to run the tests for a specific environment only, pass the ``-e`` option to tox: .. code-block:: bash $ tox -e py27 # or $ tox -e docs To run only a certain test, you can also invoke tox like this: .. code-block:: bash $ tox -e py27 -- tests.SomeUnitTestClass.test_something .. _tox: http://tox.testrun.org/latest/ .. _contributing-process-tests-coverage: 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-process-documentation: 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. .. _Sphinx: http://sphinx.pocoo.org/ .. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/introduction.html .. _contributing-process-documentation-build: 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: .. code-block:: bash (sandglass)$ cd path/to/sandglass/code/ (sandglass)$ cd docs/ (sandglass)$ make clean (sandglass)$ make html Also, as outlined in :ref:`contributing-process-tests-running`, you can use tox to build the documentation: .. code-block:: bash $ cd path/to/sandglass/code/ $ tox -e docs