From 6b8c462d6605341318279a9ab11cc6843642e230 Mon Sep 17 00:00:00 2001
From: Will Thames <wthames@redhat.com>
Date: Fri, 19 Jun 2015 12:40:56 +1000
Subject: [PATCH] Add GUIDELINES for AWS module development

Starting point for a reference when doing pull request reviews.
If something doesn't meet the guidelines we can point people
at them. If something is bad but is not mentioned in the
guidelines, we should add it here.
---
 cloud/amazon/GUIDELINES.md | 88 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 cloud/amazon/GUIDELINES.md

diff --git a/cloud/amazon/GUIDELINES.md b/cloud/amazon/GUIDELINES.md
new file mode 100644
index 00000000000..ee5aea90ef7
--- /dev/null
+++ b/cloud/amazon/GUIDELINES.md
@@ -0,0 +1,88 @@
+Guidelines for AWS modules
+--------------------------
+
+Naming your module
+==================
+
+Base the name of the module on the part of AWS that
+you actually use. (A good rule of thumb is to take
+whatever module you use with boto as a starting point).
+
+Don't further abbreviate names - if something is a well
+known abbreviation due to it being a major component of
+AWS, that's fine, but don't create new ones independently
+(e.g. VPC, ELB, etc. are fine)
+
+Using boto
+==========
+
+Wrap the `import` statements in a try block and fail the
+module later on if the import fails
+
+```
+try:
+    import boto
+    import boto.module.that.you.use
+    HAS_BOTO = True
+except ImportError:
+    HAS_BOTO = False
+
+<lots of code here>
+
+def main():
+    argument_spec = ec2_argument_spec()
+    argument_spec.update(
+        dict(
+            module_specific_parameter=dict(),
+        )
+    )
+
+    module = AnsibleModule(
+        argument_spec=argument_spec,
+    )
+    if not HAS_BOTO:
+        module.fail_json(msg='boto required for this module')
+```
+
+
+Try and keep backward compatibility with relatively recent
+versions of boto. That means that if want to implement some
+functionality that uses a new feature of boto, it should only 
+fail if that feature actually needs to be run, with a message
+saying which version of boto is needed.
+
+Use feature testing (e.g. `hasattr('boto.module', 'shiny_new_method')`)
+to check whether boto supports a feature rather than version checking
+
+e.g. from the `ec2` module:
+```
+if boto_supports_profile_name_arg(ec2):
+    params['instance_profile_name'] = instance_profile_name
+else:
+    if instance_profile_name is not None:
+        module.fail_json(
+            msg="instance_profile_name parameter requires Boto version 2.5.0 or higher")
+```
+
+
+Connecting to AWS
+=================
+
+For EC2 you can just use
+
+```
+ec2 = ec2_connect(module)
+```
+
+For other modules, you should use `get_aws_connection_info` and then
+`connect_to_aws`. To connect to an example `xyz` service:
+
+```
+region, ec2_url, aws_connect_params = get_aws_connection_info(module)
+xyz = connect_to_aws(boto.xyz, region, **aws_connect_params)
+```
+
+The reason for using `get_aws_connection_info` and `connect_to_aws`
+(and even `ec2_connect` uses those under the hood) rather than doing it
+yourself is that they handle some of the more esoteric connection
+options such as security tokens and boto profiles.