mirror of
https://github.com/ansible-collections/community.general.git
synced 2025-07-24 13:50:22 -07:00
english corrections (#35307)
This commit is contained in:
parent
2f7d207d7a
commit
4956bfd4c4
1 changed files with 11 additions and 11 deletions
|
@ -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.
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue