How to Contribute¶
Contributions are welcome! Not familiar with the codebase yet? No problem! There are many ways to contribute to open source projects: reporting bugs, helping with the documentation, spreading the word and of course, adding new features and patches.
- Make sure you have a GitHub account.
- Open a new issue, assuming one does not already exist.
- Clearly describe the issue including steps to reproduce when it is a bug.
- Fork the repository on GitHub.
- Create a topic branch from where you want to base your work.
- This is usually the
- Please avoid working directly on
- Make commits of logical units (if needed rebase your feature branch before submitting it).
- Check for unnecessary whitespace with
git diff --checkbefore committing.
- Make sure your commit messages are in the proper format.
- If your commit fixes an open issue, reference it in the commit message (#15).
- Make sure your code comforms to PEP8.
- Make sure you have added the necessary tests for your changes.
- Run all the tests to assure nothing else was accidentally broken.
- Don’t forget to add yourself to AUTHORS.
These guidelines also apply when helping with documentation (actually, for typos and minor additions you might choose to fork and edit).
- Push your changes to a topic branch in your fork of the repository.
- Submit a Pull Request.
- Wait for maintainer feedback.
First time contributor?¶
It’s alright. We’ve all been there.
Dont’ know where to start?¶
There are usually several TODO comments scattered around the codebase, maybe check them out and see if you have ideas, or can help with them. Also, check the open issues in case there’s something that sparks your interest. What about documentation? I suck at english so if you’re fluent with it (or notice any error), why not help with that? In any case, other than GitHub help pages, you might want to check this excellent Effective Guide to Pull Requests
Running the Tests¶
Cerberus runs under Python 2.6, 2.7, 3.3, 3.4, 3.5, PyPy and PyPy3. Therefore tests will be run in those four platforms in our continuous integration server.
The easiest way to get started is to run the tests in your local environment with:
$ python setup.py test
Testing with other Python versions¶
Before you submit a pull request, make sure your tests and changes run in all supported python versions: 2.6, 2.7, 3.3, 3.4 and PyPy. Instead of creating all those environments by hand, Cerberus uses tox.
Make sure you have all required python versions installed and run:
$ pip install tox # First time only $ tox
This might take some time the first run as the different virtual environments are created and dependencies are installed. If everything is ok, you will see the following:
_________ summary _________ py26: commands succeeded py27: commands succeeded py33: commands succeeded py34: commands succeeded pypy: commands succeeded flake8: commands succeeded congratulations :)
If something goes wrong and one test fails, you might need to run that test in the specific python version. You can use the created environments to run some specific tests. For example, if a test suite fails in Python 3.4:
# From the project folder $ tox -e py34
Have a look at
/tox.ini for the available test environments and their workings.
You also choose to run the whole test suite using pytest:
# Run the whole test suite $ py.test
If you have a running Docker-daemon running you can run tests from a container
that has the necessary interpreters and packages installed and pass arguments
# in the project's root directory $ ./run-docker-tests -e pypy3 -e doctest
You can run the script without any arguments to test the project exactly as
Continuous Integration does without having to setup anything.
If there’s a directoy
.tox in the project-folder it will be used to store
and access cached virtual environments and test-logs.
Building the HTML-documentation¶
To preview the rendered HTML-documentation you must intially install the documentation framework and a theme:
# in the project's root directory $ pip install -r requirements-docs.txt
The HTML build is triggered with:
# in 'docs'-folder $ make html
The result can be accessed by opening
Each time code is pushed to the
master branch the whole test-suite is
executed on Travis-CI.
This is also the case for pull-requests. A box at the bottom of its
conversation-view will inform about the tests’ status.
The contributor can then fix the code, add commits, squash the commits and
The CI will also run flake8 so make sure that your code complies to PEP8 and
test links and sample-code in the documentation.