| title: | Coding Standards |
|---|---|
| description: | Deis project coding standards. Contributors to Deis should feel welcome to make changes to any part of the codebase. |
| 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.
Before the pull request is merged, make sure that you squash your
commits into logical units of work using git rebase -i and
git push -f. Include documentation changes in the same commit,
so that a revert would remove all traces of the feature or fix.
Commits that fix or close an issue should include a reference like Closes #XXX or Fixes #XXX in the commit message. Doing so will automatically close the GitHub issue when the pull request is merged.
Deis maintainers add "LGTM" (Looks Good To Me) in code review comments to indicate that a PR is acceptable. Any code change--other than a simple typo fix or one-line documentation change--requires at least two of Deis' maintainers to accept the change in this manner before it can be merged.