Submitting patches

• If you have access to the mimic repository, always make a new branch for your work.
• If you don’t have access to the mimic repository, working on branches in your fork is also nice because that will you can work on more than one PR at a time.
• Patches should be small to facilitate easier review.

Code

When in doubt, refer to PEP 8 for Python code (with some exceptions). You can check if your code meets our automated requirements by running flake8 against it. Even better would be to run the tox job:

$ tox -e lint
...
  lint: commands succeeded
  congratulations :)

Write comments as complete sentences.

Every Python code file must contain:

from __future__ import absolute_import, division

Tests

All code changes must be accompanied by unit tests with 100% code coverage (as measured by the tool coverage.)

To test code coverage you’ll need to install detox and coverage. They can be installed by running:

pip install --user requirements/toolchain.txt

(Or you may prefer to install those requirements in a virtualenv.)

Then run:

$ coverage erase \
  && detox \
  && coverage combine \
  && coverage html

And open htmlcov/index.html in your web browser.

Documentation

All features should be documented with prose in the docs section. To ensure it builds and passes style checks you can run doc8 against it or run our tox job to lint docs. We also provide a spell-check job for docs:

$ tox -e docs
  docs: commands succeeded
  congratulations :)

$ tox -e docs-spellcheck
  docs-spellcheck: commands succeeded
  congratulations :)

$ tox -e docs-linkcheck
  docs-linkcheck: commands succeeded
  congratulations :)

The spell-check can catch jargon or abbreviations - if you are sure it is not an error, please add that word to the spelling_wordlist.txt in alphabetical order.

Docstrings

Docstrings generally follow pep257, with a few exceptions. They should be written like this:

def some_function(some_arg):
    """
    Does some things.

    :param some_arg: Some argument.
    """

So, specifically:

• Always use three double quotes.
• Put the three double quotes on their own line.
• No blank line at the end.
• Use Sphinx parameter/attribute documentation syntax.

The same job that lints code also lints docstrings:

$ tox -e lint
...
  lint: commands succeeded
  congratulations :)