From 4a741587b4cafe2666e230c7d9420cfddea9df77 Mon Sep 17 00:00:00 2001
From: Mike Perez <thingee@gmail.com>
Date: Thu, 25 Jul 2013 12:48:59 -0700
Subject: [PATCH] Updating HACKING file

Using OpenStack HACKING file for common stuff and mentioning locals()
disallowed now like Cinder.

Change-Id: I05b1706eb52c13b9eb89fe5cbcce005c3cc75caf
---
 HACKING     | 115 ----------------------------------------------------
 HACKING.rst |  70 ++++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+), 115 deletions(-)
 delete mode 100644 HACKING
 create mode 100644 HACKING.rst

diff --git a/HACKING b/HACKING
deleted file mode 100644
index 3b82d9cac..000000000
--- a/HACKING
+++ /dev/null
@@ -1,115 +0,0 @@
-Cinder Style Commandments
-=========================
-
-Step 1: Read http://www.python.org/dev/peps/pep-0008/
-Step 2: Read http://www.python.org/dev/peps/pep-0008/ again
-Step 3: Read on
-
-Imports
--------
-- thou shalt not import objects, only modules
-- thou shalt not import more than one module per line
-- thou shalt not make relative imports
-- thou shalt organize your imports according to the following template
-
-::
-  # vim: tabstop=4 shiftwidth=4 softtabstop=4
-  {{stdlib imports in human alphabetical order}}
-  \n
-  {{cinder imports in human alphabetical order}}
-  \n
-  \n
-  {{begin your code}}
-
-
-General
--------
-- thou shalt put two newlines twixt toplevel code (funcs, classes, etc)
-- thou shalt put one newline twixt methods in classes and anywhere else
-- thou shalt not write "except:", use "except Exception:" at the very least
-- thou shalt include your name with TODOs as in "TODO(termie)"
-- thou shalt not name anything the same name as a builtin or reserved word
-- thou shalt not violate causality in our time cone, or else
-
-
-Human Alphabetical Order Examples
----------------------------------
-::
-  import httplib
-  import logging
-  import random
-  import StringIO
-  import time
-  import unittest
-
-  from cinder import flags
-  from cinder import test
-  from cinder.auth import users
-  from cinder.endpoint import api
-  from cinder.endpoint import cloud
-
-Docstrings
-----------
-  """A one line docstring looks like this and ends in a period."""
-
-
-  """A multiline 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. After
-  you have finished your descriptions add an extra newline and close the
-  quotations.
-
-  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.
-
-  :param foo: the foo parameter
-  :param bar: the bar parameter
-  :returns: description of the return value
-
-  """
-
-Text encoding
-----------
-- All text within python code should be of type 'unicode'.
-
-    WRONG:
-
-    >>> s = 'foo'
-    >>> s
-    'foo'
-    >>> type(s)
-    <type 'str'>
-
-    RIGHT:
-
-    >>> u = u'foo'
-    >>> u
-    u'foo'
-    >>> type(u)
-    <type 'unicode'>
-
-- Transitions between internal unicode and external strings should always
-  be immediately and explicitly encoded or decoded.
-
-- All external text that is not explicitly encoded (database storage,
-  commandline arguments, etc.) should be presumed to be encoded as utf-8.
-
-    WRONG:
-
-    mystring = infile.readline()
-    myreturnstring = do_some_magic_with(mystring)
-    outfile.write(myreturnstring)
-
-    RIGHT:
-
-    mystring = infile.readline()
-    mytext = s.decode('utf-8')
-    returntext = do_some_magic_with(mytext)
-    returnstring = returntext.encode('utf-8')
-    outfile.write(returnstring)
diff --git a/HACKING.rst b/HACKING.rst
new file mode 100644
index 000000000..ed887f5f7
--- /dev/null
+++ b/HACKING.rst
@@ -0,0 +1,70 @@
+Cinder Client Style Commandments
+=========================
+
+- Step 1: Read the OpenStack Style Commandments
+  https://github.com/openstack-dev/hacking/blob/master/HACKING.rst
+- Step 2: Read on
+
+Cinder Client Specific Commandments
+----------------------------
+
+General
+-------
+- Do not use locals(). Example::
+
+    LOG.debug(_("volume %(vol_name)s: creating size %(vol_size)sG") %
+              locals()) # BAD
+
+    LOG.debug(_("volume %(vol_name)s: creating size %(vol_size)sG") %
+              {'vol_name': vol_name,
+               'vol_size': vol_size}) # OKAY
+
+- Use 'raise' instead of 'raise e' to preserve original traceback or exception being reraised::
+
+    except Exception as e:
+        ...
+        raise e  # BAD
+
+    except Exception:
+        ...
+        raise  # OKAY
+
+Text encoding
+----------
+- All text within python code should be of type 'unicode'.
+
+    WRONG:
+
+    >>> s = 'foo'
+    >>> s
+    'foo'
+    >>> type(s)
+    <type 'str'>
+
+    RIGHT:
+
+    >>> u = u'foo'
+    >>> u
+    u'foo'
+    >>> type(u)
+    <type 'unicode'>
+
+- Transitions between internal unicode and external strings should always
+  be immediately and explicitly encoded or decoded.
+
+- All external text that is not explicitly encoded (database storage,
+  commandline arguments, etc.) should be presumed to be encoded as utf-8.
+
+    WRONG:
+
+    mystring = infile.readline()
+    myreturnstring = do_some_magic_with(mystring)
+    outfile.write(myreturnstring)
+
+    RIGHT:
+
+    mystring = infile.readline()
+    mytext = s.decode('utf-8')
+    returntext = do_some_magic_with(mytext)
+    returnstring = returntext.encode('utf-8')
+    outfile.write(returnstring)