From 18a0813d9b3896159a4ed4819cc15e00a4a9cc03 Mon Sep 17 00:00:00 2001 From: Chmouel Boudjnah Date: Mon, 15 Jul 2013 17:14:16 +0200 Subject: [PATCH] Add documentation about flake8+hacking. - Fixes bug 1201431. Change-Id: If025a41caf3a629b9efb4d67c53c423796d37a91 --- doc/source/development_guidelines.rst | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/doc/source/development_guidelines.rst b/doc/source/development_guidelines.rst index a57cfb3cbc..0a62e2c595 100644 --- a/doc/source/development_guidelines.rst +++ b/doc/source/development_guidelines.rst @@ -6,7 +6,7 @@ Development Guidelines Coding Guidelines ----------------- -For the most part we try to follow PEP 8 guidelines which can be viewed +For the most part we try to follow PEP 8 guidelines which can be viewed here: http://www.python.org/dev/peps/pep-0008/ There is a useful pep8 command line tool for checking files for pep8 @@ -17,7 +17,7 @@ Testing Guidelines ------------------ Swift has a comprehensive suite of tests that are run on all submitted code, -and it is recommended that developers execute the tests themselves to +and it is recommended that developers execute the tests themselves to catch regressions early. Developers are also expected to keep the test suite up-to-date with any submitted code changes. @@ -51,11 +51,29 @@ To execute the unit tests: - `tox -e pep8,py26` +------------ +Coding Style +------------ + +Swift use flake8 with the OpenStack `hacking`_ module to enforce +coding style. + +Install flake8 and hacking with pip or by the packages of your +Operating System. + +It is advised to integrate flake8+hacking with your editor to get it +automated and not get `caught` by Jenkins. + +For example for Vim the `syntastic`_ plugin can do this for you. + +.. _`hacking`: https://pypi.python.org/pypi/hacking +.. _`syntastic`: https://github.com/scrooloose/syntastic + ------------------------ Documentation Guidelines ------------------------ -The documentation in docstrings should follow the PEP 257 conventions +The documentation in docstrings should follow the PEP 257 conventions (as mentioned in the PEP 8 guidelines). More specifically: @@ -80,7 +98,7 @@ License and Copyright --------------------- You can have the following copyright and license statement at -the top of each source file. Copyright assignment is optional. +the top of each source file. Copyright assignment is optional. New files should contain the current year. Substantial updates can have another year added, and date ranges are not needed.::