* While not all components of Ansible must be in Python, core contributions to the Ansible repo must be written in Python. This is to maximize the ability of everyone to contribute.
* If you want to write non-Python ansible modules or inventory scripts, that's fine, but they are not going to get merged in most likely. Sorry!!
* If you want to write non-Python ansible modules or inventory scripts, that's fine, but they are not going to get merged in most likely. Sorry!!
PEP 8 and basic style checks
============================
@ -20,7 +20,7 @@ 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 must not be strictly followed in all aspects, but most of it is good advice.
* The line is limited to 160 characters.
* To run checks for things we care about, use [ansible-test](https://docs.ansible.com/ansible/dev_guide/testing_pep8.html#running-locally).
* To run checks for things we care about, use [ansible-test](https://docs.ansible.com/ansible/devel/dev_guide/testing_sanity.html).
* 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.
* Do not submit pull requests that simply adjust whitespace in the code.
@ -28,7 +28,7 @@ PEP 8 and basic style checks
Testing
=======
* Much of ansible's testing needs are in integration, not unit tests. Add module tests there.
* Much of Ansible's testing needs are in integration, not unit tests. Add module tests there.
* That being said, there are unit tests too!
* 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.
@ -42,7 +42,7 @@ Whitespace
Shebang Lines
=============
* /usr/bin/scripts should start with '/usr/bin/env python'
* module code should still use '/usr/bin/python' as this is replaced automatically by 'ansible_python_interpreter', see the FAQ in the docs for more info.
@ -60,13 +60,13 @@ Classes
* With the exception of module code (where inline is better), it is desirable to see classes in their own files.
* Classes should generally not cause side effects as soon as they are instantiated, move meaningful behavior to methods rather than constructors.
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.
* 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
@ -161,24 +161,24 @@ 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
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
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
==============
To make it clear what a module is importing, imports should not be sprinkled throughout the code.
To make it clear what a module is importing, imports should not be sprinkled throughout the code.
Python Imports should happen at the top of the file, exempting code from module_utils.
@ -203,7 +203,7 @@ Exceptions
==========
In the main body of the code, use typed exceptions where possible:
# not this
raise Exception("panic!")
@ -265,7 +265,7 @@ Use 'in':
# not this:
if x.find('foo') != -1:
# this:
# this:
if 'foo' in x:
String checks
@ -296,7 +296,7 @@ Always do "git pull --rebase" and "git rebase" vs "git pull" or "git merge". See
Always create a new branch for each pull request to avoid intermingling different features or fixes on the same branch.
@ -65,7 +65,7 @@ For instance ensuring that a specific tenant exists, is done using the following
description: Customer XYZ
state: present
A complete list of existing ACI modules is available for the latest stable release on the :ref:`list of network modules <network_modules>`. You can also view the `current development version <http://docs.ansible.com/ansible/devel/modules/list_of_network_modules.html#aci>`_.
A complete list of existing ACI modules is available for the latest stable release on the :ref:`list of network modules <network_modules>`. You can also view the `current development version <https://docs.ansible.com/ansible/devel/modules/list_of_network_modules.html#aci>`_.
John R Barker
7 years ago
committed by