diff options
Diffstat (limited to 'CODING_GUIDELINES.md')
| -rw-r--r-- | CODING_GUIDELINES.md | 26 |
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 ============== |