ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-07-24 13:50:22 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

english corrections (#35307)

Browse source
This commit is contained in:
Brian Teeman 2018-01-30 05:09:56 +00:00 • committed by scottb
commit 4956bfd4c4
1 changed files with 11 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

22
CODING_GUIDELINES.md
View file

@ -1,10 +1,10 @@
Coding Guidelines Coding Guidelines
================= =================
Hi! Thanks for interest in contributing to Ansible. Hi! Thanks for your interest in contributing to Ansible.
Here are some guidelines for contributing code. The purpose of this document are to establish what we're looking for in code contributions, and to make sure Here are some guidelines for contributing code. The purpose of this document is to establish what we're looking for in code contributions, and to make sure
new contributions know some of the conventions that we've been using. new contributors know some of the conventions that we've been using.
We don't think much of this should be too strange to readers familiar with contributing to Python projects, though it helps if we all get on the same page. We don't think much of this should be too strange to readers familiar with contributing to Python projects, though it helps if we all get on the same page.
@ -18,12 +18,12 @@ PEP 8 and basic style checks
============================ ============================
* [PEP 8](https://www.python.org/dev/peps/pep-0008/) is a great Python style guide, which you should read. * [PEP 8](https://www.python.org/dev/peps/pep-0008/) is a great Python style guide, which you should read.
* PEP 8 must not be strictly followed in all aspects, but most of it is good advice * PEP 8 must not be strictly followed in all aspects, but most of it is good advice.
* The line is limited to 160 characters. * The line is limited to 160 characters.
* To run checks for things we care about, use [ansible-test](http://docs.ansible.com/ansible/dev_guide/testing_pep8.html#running-locally). * To run checks for things we care about, use [ansible-test](http://docs.ansible.com/ansible/dev_guide/testing_pep8.html#running-locally).
* Similarly, additional checks can be made with "make pyflakes" * Similarly, additional checks can be made with "make pyflakes".
* There is no need to submit code changes for PEP 8 and pyflakes fixes, as these break attribution history. Project leadership will make these periodically. * There is no need to submit code changes for PEP 8 and pyflakes fixes, as these break attribution history. Project leadership will make these periodically.
* Do not submit pull requests that simply adjust whitespace in the code * Do not submit pull requests that simply adjust whitespace in the code.
Testing Testing
======= =======
@ -32,7 +32,7 @@ Testing
* That being said, there are unit tests too! * That being said, there are unit tests too!
* Code written must absolutely pass tests (i.e. "make tests") * Code written must absolutely pass tests (i.e. "make tests")
* You should anticipate any error paths in your code and test down those error paths. * You should anticipate any error paths in your code and test down those error paths.
* Additions to tests for core code is welcome, but not always possible. Be sure things are at least well tested manually in that case. * Additions to tests for core code are welcome, but not always possible. Be sure things are at least well tested manually in that case.
Whitespace Whitespace
========== ==========
@ -74,7 +74,7 @@ Functions and Methods
Variables Variables
========= =========
* Use descriptive variable names instead of variables like 'x', unless x is a obvious loop index * Use descriptive variable names instead of variables like 'x', unless x is an obvious loop index
* 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
@ -83,7 +83,7 @@ Module Security
* Modules must take steps to avoid passing user input from the shell and always check return codes * 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 * 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 need to use the shell you must pass use_unsafe_shell=True to module.run_command
* if you do not need the shell, avoid using the shell * 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) * any variables that can come from the user input with use_unsafe_shell=True must be wrapped by pipes.quote(x)
* downloads of https:// resource urls must import module_utils.urls and use the fetch_url method * downloads of https:// resource urls must import module_utils.urls and use the fetch_url method
@ -294,7 +294,7 @@ Pull requests cannot be accepted that contain merge commits.
Always do "git pull --rebase" and "git rebase" vs "git pull" or "git merge". Always do "git pull --rebase" and "git rebase" vs "git pull" or "git merge".
Always create a new branch for each pull request to avoid intertwingling different features or fixes on the same branch. Always create a new branch for each pull request to avoid intermingling different features or fixes on the same branch.
Python Version Compliance Python Version Compliance
@ -302,7 +302,7 @@ Python Version Compliance
All code in Ansible core must support a minimum version of Python 2.6. All code in Ansible core must support a minimum version of Python 2.6.
Module code must support a minimum of Python 2.4, with occasional exception for modules that require code that themselves require 2.6 and later. Module code must support a minimum of Python 2.4, with occasional exceptions for modules that require code that themselves require 2.6 and later.
A quick reminder is that list comprehensions in Python 2.4 are not as fully fleshed out, there are no 'dict' comprehensions, and there is no 'with' statement. A quick reminder is that list comprehensions in Python 2.4 are not as fully fleshed out, there are no 'dict' comprehensions, and there is no 'with' statement.
But otherwise it's pretty much all the same. But otherwise it's pretty much all the same.