From aa6505af09e2fe69e961cefb1e8af0b751f03455 Mon Sep 17 00:00:00 2001
From: Monty Taylor <mordred@inaugust.com>
Date: Sat, 20 Aug 2016 13:30:02 -0500
Subject: [PATCH] Update HACKING.rst with a couple of shade specific notes

Reasonable people disagree on finer points of style. However, it's
pretty well understood that being consistent within a single codebase is
more important that specific choices globally.

There are a few things worth pointing out that are true in the context
of shade which may not be true in other places, so active communication
is likely the best choice here.

Change-Id: Ib1ceb5d6f51f84fa4bc40e68e9e231a60138507d
---
 HACKING.rst | 49 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 2 deletions(-)

diff --git a/HACKING.rst b/HACKING.rst
index 7f3d25675..82e34ce37 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -1,4 +1,49 @@
 shade Style Commandments
-===============================================
+========================
 
-Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/
\ No newline at end of file
+Read the OpenStack Style Commandments
+http://docs.openstack.org/developer/hacking/
+
+Indentation
+-----------
+
+PEP-8 allows for 'visual' indentation. Do not use it. Visual indentation looks
+like this:
+
+.. code-block:: python
+
+  return_value = self.some_method(arg1, arg1,
+                                  arg3, arg4)
+
+Visual indentation makes refactoring the code base unneccesarily hard.
+
+Instead of visual indentation, use this:
+
+.. code-block:: python
+
+  return_value = self.some_method(
+      arg1, arg1, arg3, arg4)
+
+That way, if some_method ever needs to be renamed, the only line that needs
+to be touched is the line with some_method. Additionaly, if you need to
+line break at the top of a block, please indent the continuation line
+an additional 4 spaces, like this:
+
+.. code-block:: python
+
+  for val in self.some_method(
+          arg1, arg1, arg3, arg4):
+      self.do_something_awesome()
+
+Neither of these are 'mandated' by PEP-8. However, they are prevailing styles
+within this code base.
+
+Unit Tests
+----------
+
+Unit tests should be virtually instant. If a unit test takes more than 1 second
+to run, it is a bad unit test. Honestly, 1 second is too slow.
+
+All unit test classes should subclass `shade.tests.unit.base.BaseTestCase`. The
+base TestCase class takes care of properly creating `OpenStackCloud` objects
+in a way that protects against local environment.