Add section on how to return boto3 CamelCased results (#2279)

1 files changed, 22 insertions, 0 deletions

diff --git a/cloud/amazon/GUIDELINES.md b/cloud/amazon/GUIDELINES.md
index dbfd3ee1..b8ca836b 100644
--- a/cloud/amazon/GUIDELINES.md
+++ b/cloud/amazon/GUIDELINES.md
@@ -211,6 +211,28 @@ except ClientError, e:
         module.fail_json(msg=e.message, **camel_dict_to_snake_dict(e.response))
 ```
 
+### Returning Values
+
+When you make a call using boto3, you will probably get back some useful information that you should return in the module.
+
+As well as information related to the call itself, you will also have some response metadata.  It is OK to return this to
+the user as well as they may find it useful.
+
+Boto3 returns all values CamelCased.  Ansible follows Python standards for variable names and uses snake_case. There is a
+helper function in module_utils/ec2.py called `camel_dict_to_snake_dict` that allows you to easily convert the boto3
+response to snake_case.
+
+You should use this helper function and avoid changing the names of values returned by Boto3.  E.g. if boto3 returns a
+value called 'SecretAccessKey' do not change it to 'AccessKey'.
+
+```python
+# Make a call to AWS
+result = connection.aws_call()
+
+# Return the result to the user
+module.exit_json(changed=True, **camel_dict_to_snake_dict(result))
+```
+
 ### Helper functions
 
 Along with the connection functions in Ansible ec2.py module_utils, there are some other useful functions detailed below.