cloudroast/HACKING.rst

CloudCafe Style Guide

General Guidelines

1. It is HIGHLY encouraged that if you have not already read (and even if it's been a while since you have) the Python Enhancement Proposals (PEPs) PEP-8 and PEP 20 that you do so.
2. Guidelines here are intended to help encourage code unity, they are not unbreakable rules, but should be adhered to failing a good reason not to.
3. When in doubt, ALL code should conform either directly to or in the spirit of Python PEP 20, if you are still in doubt, go with Python PEP-8.
4. If you really are still in doubt, see Guideline 2.
5. Base Classes are your friend. Use them when they make sense.

Development Guidelines

• Always use SPACES. NEVER TABS. All block indention should be four (4) spaces.
• Avoid single letter variable names except in the case of iterators, in which case a descriptive variable name would still be preferable if possible.
• Do not leave trailing whitespace or whitespace in blank lines.
• Put two newlines between top-level code (funcs, classes, etc).
• Use only UNIX style newlines ("n"), not Windows style ("rn").
• 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
• Use try/except where logical. Avoid wrapping large blocks of code in in huge try/except blocks.
• Use Enumerated Types where logical to pass around string constants or magic numbers between Functions, Methods, Classes and Packages. Python does not provide a default Enumerated Type data type, CloudCafe uses Class structs by naming convention in their place.

Example::

class ComputeServerStates(object):

ACTIVE = "ACTIVE" BUILD = "BUILD" REBUILD = "REBUILD" ERROR = "ERROR" DELETING = "DELETING" DELETED = "DELETED" RESCUE = "RESCUE" PREP_RESCUE = "PREP_RESCUE" RESIZE = "RESIZE" VERIFY_RESIZE = "VERIFY_RESIZE"

- Blocks of code should either be self documenting and/or well commented,

especially in cases of non-standard code.

- Use Python list comprehensions when possible. They can make large blocks

of code collapse to a single line.

- String formatting via the new (as of python 2.4) .format() method is

preferred over the older %s style encoding and ''.join() methods. (Note on ''.join(): This is OK to use and encouraged if you're actually creating a string from a large list of strings. Otherwise, ''.format() is the better choice).

Test Data/Configuration

• Tests should make no assumptions on data exists. Test data should either be generated in a fixture, or be provided in a configuration file.
• Tests should be self contained. They should not rely on changes in state not performed in the test. The one exception to this rule is ordered tests, but even those are discouraged unless absolutely necessary.
• Each test/test class is responsible for deleting/or removing any resources creating during the test.

Imports

• Do not use wildcard * import
• Do not make relative imports
• Order your imports by the full module path

Docstrings

Example:

"""A one line docstring looks like this and ends in a period."""


"""A multi line docstring has a one-line summary, less than 80 characters.

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.

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/
"""

Before Committing

• Follow the general OpenStack submission workflow (http://docs.openstack.org/infra/manual/developers.html#development-workflow). This means all all submissions should be squashed into one commit with one commit id and be submitted from a feature branch, not master.
• Always run a PEP8 check on your modified code before committing. You can do this with a plethora of tools such as flake8, pylint, and pyflakes. Once gating on PEP-8 rules is enabled, Gerrit will immediately reject any submission with PEP-8 issues.
• Blocks of commented out code should not be submitted to trunk except in extraordinary cases.
• Tests that either validate nothing or simply have the "pass" statement should not be submitted.
• Only functional, TESTED CODE should be committed. There are no exceptions. This includes verify that code for other projects has not been broken if your changes effect common code. Until a gate job is in place, it is not time efficient for reviewers to execute all submitted code.

Commit Messages

Using a common format for commit messages will help keep our git history readable. Follow these guidelines:

First, provide a brief summary of 50 characters or less.

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.

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