From d42cfb338609e3992e3f16c91e000e80b57a0aad Mon Sep 17 00:00:00 2001
From: Brian Coca <brian.coca+git@gmail.com>
Date: Mon, 18 May 2015 08:57:22 -0400
Subject: [PATCH 1/2] added module checklist docs

---
 docsite/rst/developing_modules.rst | 38 ++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docsite/rst/developing_modules.rst b/docsite/rst/developing_modules.rst
index 3b563ee755f..44051d3c689 100644
--- a/docsite/rst/developing_modules.rst
+++ b/docsite/rst/developing_modules.rst
@@ -449,6 +449,44 @@ a github pull request to the `extras <https://github.com/ansible/ansible-modules
 Included modules will ship with ansible, and also have a chance to be promoted to 'core' status, which
 gives them slightly higher development priority (though they'll work in exactly the same way).
 
+Module checklist
+````````````````
+
+* The shebang should always be #!/usr/bin/python, this allows ansible_python_interpreter to work
+* Documentation: Make sure it exists
+  * `required` should always be present, be it true or false
+  * If `required` is false you need to document `default`, even if its 'null'
+  * `default` is not needed for `required: true`
+  * Remove unnecessary doc like `aliases: []` or `choices: []`
+  * The version is not a float number and value the current development version
+  * The verify that arguments in doc and module spec dict are identical
+  * For password / secret arguments no_log=True should be set
+  * Requirements should  be documented, using the `requirements=[]` field
+  * Author should be set, name and github id at least
+  * Made use of U() for urls, C() for files and options, I() for params, M() for modules?
+  * GPL License header
+  * Examples: make sure they are reproducible
+* Does module use check_mode? Could it be modified to use it? Document it
+* Exceptions: The module must handle them. (exceptions are bugs)
+    * Give out useful messages on what you were doing and you can add the exception message to that.
+    * Avoid catchall exceptions, they are not very useful unless the underlying API gives very good error messages pertaining the attempted action.
+* The module must not use sys.exit() --> use fail_json() from the module object
+* Import custom packages in try/except and handled with fail_json() in main() e.g.::
+
+  try:
+    import foo
+    HAS_LIB=True
+  except:
+    HAS_LIB=False
+
+* Are module actions idempotent? If not document in the descriptions or the notes
+* Import module snippets `from ansible.module_utils.basic import *` at the bottom, conserves line numbers for debugging.
+* Try to normalize parameters with other modules, you can have aliases for when user is more familiar with underlying API name for the option
+* Being pep8 compliant is nice, but not a requirement. Specifically, the 80 column limit now hinders readability more that it improves it
+* Avoid '`action`/`command`', they are imperative and not declarative, there are other ways to express the same thing
+* Sometimes you want to split the module, specially if you are adding a list/info state, you want a _facts version
+* If you are asking 'how can i have a module execute other modules' ... you want to write a role
+
 
 Deprecating and making module aliases
 ``````````````````````````````````````

From 6c1e806a2f538d1fc4d18eb4ed4fcb2eeb887dcd Mon Sep 17 00:00:00 2001
From: Brian Coca <brian.coca+git@gmail.com>
Date: Mon, 18 May 2015 09:57:44 -0400
Subject: [PATCH 2/2] added return docs management

---
 docsite/rst/developing_modules.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docsite/rst/developing_modules.rst b/docsite/rst/developing_modules.rst
index 44051d3c689..dd4d6b4d7ad 100644
--- a/docsite/rst/developing_modules.rst
+++ b/docsite/rst/developing_modules.rst
@@ -466,12 +466,14 @@ Module checklist
   * Made use of U() for urls, C() for files and options, I() for params, M() for modules?
   * GPL License header
   * Examples: make sure they are reproducible
+  * Return: document the return structure of the module
 * Does module use check_mode? Could it be modified to use it? Document it
 * Exceptions: The module must handle them. (exceptions are bugs)
     * Give out useful messages on what you were doing and you can add the exception message to that.
     * Avoid catchall exceptions, they are not very useful unless the underlying API gives very good error messages pertaining the attempted action.
 * The module must not use sys.exit() --> use fail_json() from the module object
 * Import custom packages in try/except and handled with fail_json() in main() e.g.::
+* The return structure should be consistent, even if NA/None are used for keys normally returned under other options.
 
   try:
     import foo