From eeae22fb7f6e179f4371fcbf82367918df091a00 Mon Sep 17 00:00:00 2001
From: David Shrewsbury <shrewsbury.dave@gmail.com>
Date: Mon, 10 Aug 2015 09:17:02 -0400
Subject: [PATCH] Add a developer coding standards doc

We have coding standards. Let's tell others about them.

Change-Id: I36456fa706db96ad1abb3d121f90981845065d8c
---
 doc/source/coding.rst | 89 +++++++++++++++++++++++++++++++++++++++++++
 doc/source/index.rst  |  1 +
 2 files changed, 90 insertions(+)
 create mode 100644 doc/source/coding.rst

diff --git a/doc/source/coding.rst b/doc/source/coding.rst
new file mode 100644
index 000000000..be67398ca
--- /dev/null
+++ b/doc/source/coding.rst
@@ -0,0 +1,89 @@
+********************************
+Shade Developer Coding Standards
+********************************
+
+In the beginning, there were no guidelines. And it was good. But that
+didn't last long. As more and more people added more and more code,
+we realized that we needed a set of coding standards to make sure that
+the shade API at least *attempted* to display some form of consistency.
+
+Thus, these coding standards/guidelines were developed. Note that not
+all of shade adheres to these standards just yet. Some older code has
+not been updated because we need to maintain backward compatibility.
+Some of it just hasn't been changed yet. But be clear, all new code
+*must* adhere to these guidelines.
+
+Below are the patterns that we expect Shade developers to follow.
+
+API Methods
+===========
+
+- When an API call acts on a resource that has both a unique ID and a
+  name, that API call should accept either identifier with a name_or_id
+  parameter.
+
+- All resources should adhere to the get/list/search interface that
+  control retrieval of those resources. E.g., `get_image()`, `list_images()`,
+  `search_images()`.
+
+- Resources should have `create_RESOURCE()`, `delete_RESOURCE()`,
+  `update_RESOURCE()` API methods (as it makes sense).
+
+- For those methods that should behave differently for omitted or None-valued
+  parameters, use the `valid_kwargs` decorator. Notably: all Neutron
+  `update_*` functions.
+
+- Deleting a resource should return True if the delete succeeded, or False
+  if the resource was not found.
+
+Exceptions
+==========
+
+All underlying client exceptions must be captured and converted to an
+`OpenStackCloudException` or one of its derivatives.
+
+Client Calls
+============
+
+All underlying client calls (novaclient, swiftclient, etc.) must be
+wrapped by a Task object.
+
+Returned Resources
+==================
+
+Complex objects returned to the caller must be a dict type. The
+methods `obj_to_dict()` or `obj_list_to_dict()` should be used for this.
+
+As of this writing, those two methods are returning Bunch objects, which help
+to maintain backward compatibility with a time when shade returned raw
+objects. Bunch allows the returned resource to act as *both* an object
+and a dict. Use of Bunch objects will eventually be deprecated in favor
+of just pure dicts, so do not depend on the Bunch object functionality.
+Expect a pure dict type.
+
+Nova vs. Neutron
+================
+
+- Recognize that not all cloud providers support Neutron, so never
+  assume it will be present. If a task can be handled by either
+  Neutron or Nova, code it to be handled by either.
+
+- For methods that accept either a Nova pool or Neutron network, the
+  parameter should just refer to the network, but documentation of it
+  should explain about the pool. See: `create_floating_ip()` and
+  `available_floating_ip()` methods.
+
+Tests
+=====
+
+- New API methods *must* have unit tests!
+
+- Functional tests should be added, when possible.
+
+- In functional tests, always use unique names (for resources that have this
+  attribute) and use it for clean up (see next point).
+
+- In functional tests, always define cleanup functions to delete data added
+  by your test, should something go wrong. Data removal should be wrapped in
+  a try except block and try to delete as many entries added by the test as
+  possible.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 97455f584..af9eaa3d2 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -14,6 +14,7 @@ Contents:
    installation
    usage
    contributing
+   coding
    future
 
 .. include:: ../../README.rst