From 637740a4f1aa64e192c05638b76ad2355909e346 Mon Sep 17 00:00:00 2001 From: Steven Dake Date: Wed, 27 Feb 2013 10:26:46 -0700 Subject: Update infrastructure to more closely match other OpenStack projects This patch imports nova's HACKING.rst guidelines altered for Heat. This patch imports nova's run_pep8.sh with some minor alterations. This patch imports nova's hacking.py extensions to pep8. This patch places the run_pep8 logic in a separate file rather than having it spread between tox.ini and run_tests.sh. The HACKING.rst requirements as well as general pep8 requirements are then enforced with run_pep8.sh. Avoid running once the N802 rule until dependency changelogs are less then 50 characters. Change-Id: If46c14668eae3cf11b8fbff46d766cc589d701aa Fixes: Bug #1131275 --- HACKING.rst | 156 +++++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 127 insertions(+), 29 deletions(-) (limited to 'HACKING.rst') diff --git a/HACKING.rst b/HACKING.rst index a7e691113..2692e7af5 100644 --- a/HACKING.rst +++ b/HACKING.rst @@ -1,4 +1,4 @@ -Glance Style Commandments +Heat Style Commandments ======================= - Step 1: Read http://www.python.org/dev/peps/pep-0008/ @@ -9,18 +9,62 @@ Glance Style Commandments General ------- - Put two newlines between top-level code (funcs, classes, etc) +- Use only UNIX style newlines ("\n"), not Windows style ("\r\n") - Put one newline between methods in classes and anywhere else +- Long lines should be wrapped in parentheses + in preference to using a backslash for line continuation. - Do not write "except:", use "except Exception:" at the very least - Include your name with TODOs as in "#TODO(termie)" -- Do not name anything the same name as a built-in or reserved word -- Do declare variable names that conflict with the debugger, such as the letter 'c' +- Do not shadow a built-in or reserved word. Example:: + + def list(): + return [1, 2, 3] + + mylist = list() # BAD, shadows `list` built-in + + class Foo(object): + def list(self): + return [1, 2, 3] + + mylist = Foo().list() # OKAY, does not shadow built-in + +- Use the "is not" operator when testing for unequal identities. Example:: + + if not X is Y: # BAD, intended behavior is ambiguous + pass + + if X is not Y: # OKAY, intuitive + pass + +- Use the "not in" operator for evaluating membership in a collection. Example:: + + if not X in Y: # BAD, intended behavior is ambiguous + pass + + if X not in Y: # OKAY, intuitive + pass + + if not (X in Y or X in Z): # OKAY, still better than all those 'not's + pass + Imports ------- +- Do not import objects, only modules (*) +- Do not import more than one module per line (*) +- Do not use wildcard ``*`` import (*) - Do not make relative imports +- Do not make new heat.db imports in heat/virt/* - Order your imports by the full module path - Organize your imports according to the following template +(*) exceptions are: + +- imports from ``migrate`` package +- imports from ``sqlalchemy`` package +- imports from ``heat.db.sqlalchemy.session`` module +- imports from ``heat.db.sqlalchemy.migration.versioning_api`` package + Example:: # vim: tabstop=4 shiftwidth=4 softtabstop=4 @@ -28,7 +72,7 @@ Example:: \n {{third-party lib imports in human alphabetical order}} \n - {{glance imports in human alphabetical order}} + {{heat imports in human alphabetical order}} \n \n {{begin your code}} @@ -48,38 +92,30 @@ Example:: import eventlet import webob.exc - import glance.api.middleware - from glance.api import images - from glance.auth import users - import glance.common - from glance.endpoint import cloud - from glance import test + import heat.api.ec2 + from heat.api import openstack + from heat.auth import users + from heat.endpoint import cloud + import heat.flags + from heat import test Docstrings ---------- +Example:: -Docstrings are required for all functions and methods. - -Docstrings should ONLY use triple-double-quotes (``"""``) - -Single-line docstrings should NEVER have extraneous whitespace -between enclosing triple-double-quotes. - -**INCORRECT** :: + """A one line docstring looks like this and ends in a period.""" - """ There is some whitespace between the enclosing quotes :( """ -**CORRECT** :: + """A multi line docstring has a one-line summary, less than 80 characters. - """There is no whitespace between the enclosing quotes :)""" + Then a new paragraph after a newline that explains in more detail any + general information about the function, class or method. Example usages + are also great to have here if it is a complex class for function. -Docstrings that span more than one line should look like this: - -Example:: - - """ - Start the docstring on the line following the opening triple-double-quote + When writing the docstring for a class, an extra line should be placed + after the closing quotations. For more in-depth explanations for these + decisions see http://www.python.org/dev/peps/pep-0257/ If you are going to describe parameters and return values, use Sphinx, the appropriate syntax is as follows. @@ -91,8 +127,6 @@ Example:: :raises: AttributeError, KeyError """ -**DO NOT** leave an extra newline before the closing triple-double-quote. - Dictionaries/Lists ------------------ @@ -185,6 +219,29 @@ bug that had no unit test, a new passing unit test should be added. If a submitted bug fix does have a unit test, be sure to add a new one that fails without the patch and passes with the patch. +For more information on creating unit tests and utilizing the testing +infrastructure in OpenStack Heat, please read heat/testing/README.rst. + + +Running Tests +------------- +The testing system is based on a combination of tox and testr. The canonical +approach to running tests is to simply run the command `tox`. This will +create virtual environments, populate them with depenedencies and run all of +the tests that OpenStack CI systems run. Behind the scenes, tox is running +`testr run --parallel`, but is set up such that you can supply any additional +testr arguments that are needed to tox. For example, you can run: +`tox -- --analyze-isolation` to cause tox to tell testr to add +--analyze-isolation to its argument list. + +It is also possible to run the tests inside of a virtual environment +you have created, or it is possible that you have all of the dependencies +installed locally already. In this case, you can interact with the testr +command directly. Running `testr run` will run the entire test suite. `testr +run --parallel` will run it in parallel (this is the default incantation tox +uses.) More information about testr can be found at: +http://wiki.openstack.org/testr + openstack-common ---------------- @@ -199,3 +256,44 @@ with the help of openstack-common's update.py script. See: The copy of the code should never be directly modified here. Please always update openstack-common first and then run the script to copy the changes across. + +OpenStack Trademark +------------------- + +OpenStack is a registered trademark of the OpenStack Foundation, and uses the +following capitalization: + + OpenStack + + +Commit Messages +--------------- +Using a common format for commit messages will help keep our git history +readable. Follow these guidelines: + + First, provide a brief summary (it is recommended to keep the commit title + under 50 chars). + + The first line of the commit message should provide an accurate + description of the change, not just a reference to a bug or + blueprint. It must be followed by a single blank line. + + If the change relates to a specific driver (libvirt, xenapi, qpid, etc...), + begin the first line of the commit message with the driver name, lowercased, + followed by a colon. + + Following your brief summary, provide a more detailed description of + the patch, manually wrapping the text at 72 characters. This + description should provide enough detail that one does not have to + refer to external resources to determine its high-level functionality. + + Once you use 'git review', two lines will be appended to the commit + message: a blank line followed by a 'Change-Id'. This is important + to correlate this commit with a specific review in Gerrit, and it + should not be modified. + +For further information on constructing high quality commit messages, +and how to split up commits into a series of changes, consult the +project wiki: + + http://wiki.openstack.org/GitCommitMessages -- cgit v1.2.1