165 lines
4.4 KiB
ReStructuredText
165 lines
4.4 KiB
ReStructuredText
*****************
|
|
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. If the build is broken or fixed,
|
|
Hudson will issue notifications to our IRC channel.
|
|
|
|
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/docs/ is automatically updated
|
|
within 10 minutes after a documentation update is pushed to
|
|
``jodal/mopidy/master`` at GitHub.
|
|
|
|
|
|
Creating releases
|
|
=================
|
|
|
|
1. Update changelog and commit it.
|
|
|
|
2. Tag release::
|
|
|
|
git tag -a -m "Release v0.1.0a0" v0.1.0a0
|
|
|
|
3. Push to GitHub::
|
|
|
|
git push
|
|
git push --tags
|
|
|
|
4. Build package and upload to PyPI::
|
|
|
|
rm MANIFEST # Will be regenerated by setup.py
|
|
python setup.py sdist upload
|
|
|
|
5. Spread the word.
|