cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add notes about module.run_command to coding guidelines.

Browse source
This commit is contained in:
Michael DeHaan 2014-03-12 15:18:55 -04:00
parent 2c7d58abe0
commit 29c32890d5
1 changed files with 20 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
CODING_GUIDELINES.md
View file

@ -66,8 +66,10 @@ Functions and Methods
* In general, functions should not be 'too long' and should describe a meaningful amount of work * 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 * 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 have names that describe what they do, along with docstrings
* Functions should be named with_underscores * Functions should be named with_underscores
* "Don't repeat yourself" is generally a good philosophy
Variables Variables
========= =========
@ -76,6 +78,15 @@ Variables
* Ansible python code uses identifiers like 'ClassesLikeThis and variables_like_this * Ansible python code uses identifiers like 'ClassesLikeThis and variables_like_this
* Module parameters should also use_underscores and not runtogether * 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 Misc Preferences
================ ================
@ -149,16 +160,19 @@ All contributions to the core repo should preserve original licenses and new con
Module Documentation 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 All module pull requests must include a DOCUMENTATION docstring (YAML format,
is free form. 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" When adding new modules, any new parameter must have a "version_added" attribute.
attribute in the pull request as well, set to the current development version. 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. 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. It's frequently the case that modules get submitted with YAML that isn't valid,
If it fails to build, take a look at your DOCUMENTATION string or you might have a Python syntax error in there too. 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 Python Imports
============== ==============