summaryrefslogtreecommitdiff
path: root/CODING_GUIDELINES.md
diff options
context:
space:
mode:
Diffstat (limited to 'CODING_GUIDELINES.md')
-rw-r--r--CODING_GUIDELINES.md26
1 files changed, 20 insertions, 6 deletions
diff --git a/CODING_GUIDELINES.md b/CODING_GUIDELINES.md
index 7860fb2481..1ba5d5035e 100644
--- a/CODING_GUIDELINES.md
+++ b/CODING_GUIDELINES.md
@@ -66,8 +66,10 @@ Functions and Methods
* In general, functions should not be 'too long' and should describe a meaningful amount of work
* When code gets too nested, that's usually the sign the loop body could benefit from being a function
+ * Parts of our existing code are not the best examples of this at times.
* Functions should have names that describe what they do, along with docstrings
* Functions should be named with_underscores
+ * "Don't repeat yourself" is generally a good philosophy
Variables
=========
@@ -76,6 +78,15 @@ Variables
* Ansible python code uses identifiers like 'ClassesLikeThis and variables_like_this
* Module parameters should also use_underscores and not runtogether
+Module Security
+===============
+
+ * Modules must take steps to avoid passing user input from the shell and always check return codes
+ * always use module.run_command instead of subprocess or Popen or os.system -- this is mandatory
+ * if you use need the shell you must pass use_unsafe_shell=True to module.run_command
+ * if you do not need the shell, avoid using the shell
+ * any variables that can come from the user input with use_unsafe_shell=True must be wrapped by pipes.quote(x)
+
Misc Preferences
================
@@ -149,16 +160,19 @@ All contributions to the core repo should preserve original licenses and new con
Module Documentation
====================
-All module pull requests must include a DOCUMENTATION docstring (YAML format, see other modules for examples) as well as an EXAMPLES docstring, which
-is free form.
+All module pull requests must include a DOCUMENTATION docstring (YAML format,
+see other modules for examples) as well as an EXAMPLES docstring, which is free form.
-When adding new modules, any new parameter must have a "version_added" attribute. When submitting a new module, the module should have a "version_added"
-attribute in the pull request as well, set to the current development version.
+When adding new modules, any new parameter must have a "version_added" attribute.
+When submitting a new module, the module should have a "version_added" attribute in the
+pull request as well, set to the current development version.
Be sure to check grammar and spelling.
-It's frequently the case that modules get submitted with YAML that isn't valid, so you can run "make webdocs" from the checkout to preview your module's documentation.
-If it fails to build, take a look at your DOCUMENTATION string or you might have a Python syntax error in there too.
+It's frequently the case that modules get submitted with YAML that isn't valid,
+so you can run "make webdocs" from the checkout to preview your module's documentation.
+If it fails to build, take a look at your DOCUMENTATION string
+or you might have a Python syntax error in there too.
Python Imports
==============