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.

Note

There’s currently a feature freeze until the basic code modernization for the 2.0 release is finished. Have a look at the ROADMAP.md for a status on its progress.

Getting Started

  1. Make sure you have a GitHub account.
  2. Open a new issue, assuming one does not already exist.
  3. Clearly describe the issue including steps to reproduce when it is a bug.

Making Changes

  • Fork the repository on GitHub.
  • Create a topic branch from where you want to base your work.
  • This is usually the master branch.
  • Please avoid working directly on master branch.
  • Make commits of logical units (if needed rebase your feature branch before submitting it).
  • 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 you have added the necessary tests for your changes.
  • Run all the tests to assure nothing else was accidentally broken.
  • Install and enable pre-commit (pip install pre-commit, then pre-commit install) to ensure styleguides and codechecks are followed. CI will reject a change that does not conform to the guidelines.
  • 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).

Submitting Changes

  • 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.

Type annotations

There are two purposes for type annotations in the codebase: The first one is to provide information about callables’ signatures for applications such as IDEs, so they can give useful hints within the client codebase when unexpected types of values are passed to Cerberus’ interfaces. The other is to document the intended use of variables, such as bar = {}  # type: Dict[str, int]. Though testing type annotations with checkers like mypy can reveal possible problems, this is not what they’re intended for in this project. The annotations however must be checked for correctness. As Python’s typing system and the most advanced type checker aren’t mature yet and it isn’t possible to annotate every part correctly with a reasonable effort due to the nature of Cerberus architecture, there has to be a compromise to comply with the afore mentioned goals and requirement:

  1. All parts of the public API (functions, methods, class properties) must be type annotated. It is okay to cast variables and instruct type checkers to ignore errors (# type: ignore). It should occasionally be checked whether these can be removed due to progress both within Cerberus’ code and the used checker.
  2. The annotation of code that is not supposed to be used directly is helpful for maintenance and should be added if the checker doesn’t need to be pleased with the previously mentioned methods. If such are required, type annotations must not be added at all.

Don’t know where to start?

There are usually several TODO comments scattered around the codebase, maybe check them out and see if you have ideas and can help with them. Also, check the open issues in case there’s something that sparks your interest. What about documentation? We’re contributors and reviewers with different mother tongues, 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 3.5 to 3.8 and PyPy3. Therefore test will be run in those 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. Instead of creating all those environments by hand, you can use tox that automatically manages virtual environments. Mind that the interpreters themselves need to be available on the system.

$ 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 _________
py35: commands succeeded
py36: commands succeeded
py37: commands succeeded
py38: commands succeeded
pypy3: commands succeeded
doclinks: commands succeeded
doctest: commands succeeded
linting: 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.5:

$ tox -e py35

Have a look at tox.ini for the available test environments and their workings.

Using Pytest

You also choose to run the whole test suite using pytest:

$ pytest cerberus/tests

Using Docker

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 to tox:

$ ./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. The tox environments are preserved in a volume named cerberus-tox, just remove it with docker volume rm to clean them.

Running the benchmarks

There’s a benchmark suite that you can use to measure how changes imapact Cerberus’ performance:

$ pytest cerberus/benchmarks

Building the HTML-documentation

To preview the rendered HTML-documentation you must initially install the documentation framework and a theme:

$ pip install -r docs/requirements.txt

The HTML build is triggered with:

$ make -C docs html

The result can be accessed by opening docs/_build/html/index.html.

Continuous Integration

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 push again. The CI will also run flake8 so make sure that your code complies to PEP8 and test links and sample-code in the documentation.

Source Code

Source code is available at GitHub.