| title: | Coding Standards |
|---|---|
| description: | Coding Standards for the Deis Project |
| keywords: | deis, contributing, coding, python, test, tests, testing |
Deis is a Python project. We chose Python over other compelling languages because it is widespread, well-documented, and friendly to a large number of developers. Source code benefits from many eyes upon it.
The Zen of Python emphasizes simple over clever, and we agree. Readability counts. Deis also aims for complete test coverage.
Contributors to Deis should feel welcome to make changes to any part of the codebase. To create a proper GitHub pull request for inclusion into the official repository, your code must pass two tests:
flake8 is a helpful command-line tool that combines the output of pep8, pyflakes, and mccabe.
$ cd $HOME/projects/deis
$ make flake8
flake8
$No output, as above, means flake8 found no errors. If errors
are reported, fix them in your source code and try flake8 again.
The Deis project adheres to PEP8, the python code style guide,
with the exception that we allow lines up to 99 characters in length.
Docstrings and tests are also required for all public methods, although
flake8 does not enforce this.
Default settings for flake8 are in the [flake8] section of the
setup.cfg file in the project root.
Once your code passes the style checker, run the test suite and ensure that everything passes and that code coverage has not declined.
$ cd $HOME/projects/deis
$ make coverage
coverage run manage.py test api celerytasks client web
Creating test database for alias 'default'...
...................ss.
----------------------------------------------------------------------
Ran 22 tests in 22.630s
OK (skipped=2)
Destroying test database for alias 'default'...
coverage html
$If a test fails, fixing it is obviously the first priority. And if you have introduced new code, it must be accompanied by unit tests.
In the example above, all tests passed and coverage created a report
of what code was exercised while the tests were running. Open the file
htmlcov/index.html under the project's root and ensure that the
overall coverage percentage has not receded as a result of your
changes. Current test coverage can be found here:
Now create a GitHub pull request with a description of what your code fixes or improves. That's it!