@ -14,11 +14,12 @@ syntax highlighting before you include it in your Python file.
All modules must have the following sections defined in this order:
1. ANSIBLE_METADATA
2. DOCUMENTATION
3. EXAMPLES
4. RETURNS
5. Python imports
1. Copyright
2. ANSIBLE_METADATA
3. DOCUMENTATION
4. EXAMPLES
5. RETURNS
6. Python imports
.. note :: Why don't the imports go first?
@ -30,6 +31,41 @@ All modules must have the following sections defined in this order:
Copyright
----------------------
The beginning of every module should look about the same. After the shebang,
there should be at least two lines covering copyright and licensing of the
code.
.. code-block :: python
#!/usr/bin/python
# Copyright (c) 2017 Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
Every file should have a copyright line with the original copyright holder.
Major additions to the module (for instance, rewrites) may add additional
copyright lines. Code from the Ansible community should typically be assigned
as "Copyright (c) 2017 Ansible Project" which covers all contributors. Any
legal questions need to review the source control history, so an exhaustive
copyright header is not necessary.
The license declaration should be ONLY one line, not the full GPL prefix. If
you notice a module with the full prefix, feel free to switch it to the
one-line declaration instead.
When adding a copyright line after completing a significant feature or rewrite,
add the newer line above the older one, like so:
.. code-block :: python
#!/usr/bin/python
# Copyright (c) 2017 [New Contributor(s)]
# Copyright (c) 2015 [Original Contributor(s)]
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
ANSIBLE_METADATA Block
----------------------
@ -116,7 +152,8 @@ Include it in your module file like this:
.. code-block :: python
#!/usr/bin/python
# Copyright header....
# Copyright (c) 2017 [REPLACE THIS]
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
DOCUMENTATION = '''
---
@ -126,6 +163,8 @@ Include it in your module file like this:
'''
The following fields can be used and are all required unless specified otherwise:
:module: