mopidy/docs/development/contributing.rst

*****************
How to contribute
*****************

Development of Mopidy is coordinated through the IRC channel ``#mopidy`` at
``irc.freenode.net`` and through `GitHub <http://github.com/>`_.


Code style
==========

- Follow :pep:`8` unless otherwise noted. `pep8.py
  <http://pypi.python.org/pypi/pep8/>`_ can be used to check your code against
  the guidelines, however remember that matching the style of the surrounding
  code is also important.

- Use four spaces for indentation, *never* tabs.

- Use CamelCase with initial caps for class names::

      ClassNameWithCamelCase

- Use underscore to split variable, function and method names for
  readability. Don't use CamelCase.

  ::

      lower_case_with_underscores

- Use the fact that empty strings, lists and tuples are :class:`False` and
  don't compare boolean values using ``==`` and ``!=``.

- Follow whitespace rules as described in :pep:`8`. Good examples::

      spam(ham[1], {eggs: 2})
      spam(1)
      dict['key'] = list[index]

- Limit lines to 80 characters and avoid trailing whitespace. However note that
  wrapped lines should be *one* indentation level in from level above, except
  for ``if``, ``for``, ``with``, and ``while`` lines which should have two
  levels of indentation::

      if (foo and bar ...
              baz and foobar):
          a = 1

      from foobar import (foo, bar, ...
          baz)

- For consistency, prefer ``'`` over ``"`` for strings, unless the string
  contains ``'``.

- Take a look at :pep:`20` for a nice peek into a general mindset useful for
  Python coding.


Commit guidelines
=================

- We follow the development process described at http://nvie.com/git-model.

- Keep commits small and on topic.

- If a commit looks too big you should be working in a feature branch not a
  single commit.

- Merge feature branches with ``--no-ff`` to keep track of the merge.


Running tests
=============

To run tests, you need a couple of dependencies. They can be installed through
Debian/Ubuntu package management::

    sudo aptitude install python-coverage python-nose

Or, they can be installed using ``pip``::

    sudo pip install -r requirements-tests.txt

Then, to run all tests, go to the project directory and run::

    nosetests

For example::

    $ nosetests
    ......................................................................
    ......................................................................
    ......................................................................
    .......
    ----------------------------------------------------------------------
    Ran 217 tests in 0.267s

    OK

To run tests with test coverage statistics::

    nosetests --with-coverage

For more documentation on testing, check out the `nose documentation
<http://somethingaboutorange.com/mrl/projects/nose/>`_.


Continuous integration server
=============================

We run a continuous integration server called Hudson at
http://hudson.mopidy.com/ that runs all test on multiple platforms (Ubuntu, OS
X, etc.) for every commit we push to GitHub.

In addition to running tests, Hudson also does coverage statistics and uses
pylint to check for errors and possible improvements in our code. So, if you're
out of work, the code coverage and pylint data in Hudson should give you a
place to start.


Writing documentation
=====================

To write documentation, we use `Sphinx <http://sphinx.pocoo.org/>`_. See their
site for lots of documentation on how to use Sphinx. To generate HTML or LaTeX
from the documentation files, you need some additional dependencies.

You can install them through Debian/Ubuntu package management::

    sudo aptitude install python-sphinx python-pygraphviz graphviz

Then, to generate docs::

    cd docs/
    make        # For help on available targets
    make html   # To generate HTML docs

.. note::

    The documentation at http://www.mopidy.com/ is automatically updated when a
    documentation update is pushed to ``mopidy/mopidy`` at GitHub.

    Documentation generated from the ``master`` branch is published at
    http://www.mopidy.com/docs/master/, and will always be valid for the latest
    release.

    Documentation generated from the ``develop`` branch is published at
    http://www.mopidy.com/docs/develop/, and will always be valid for the
    latest development snapshot.


Creating releases
=================

#. Update changelog and commit it.

#. Merge the release branch (``develop`` in the example) into master::

    git checkout master
    git merge --no-ff -m "Release v0.2.0" develop

#. Tag the release::

    git tag -a -m "Release v0.2.0" v0.2.0

#. Push to GitHub::

    git push
    git push --tags

#. Build package and upload to PyPI::

    rm MANIFEST                         # Will be regenerated by setup.py
    python setup.py sdist upload

#. Spread the word.