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.
• New features and significant bug fixes should be documented in the Change Logs.

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 code file must start with the boilerplate notice of the Apache License. Additionally, every Python code file must contain

from __future__ import absolute_import, division, print_function

Tests

All code changes must be accompanied by unit tests with 100% code coverage (as measured by the tool coverage. To test coverage, use our tox job:

$ tox -e cover
Name                                   Stmts   Miss  Cover   Missing
--------------------------------------------------------------------
...
  cover: commands succeeded
  congratulations :)

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 :)

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 :)