diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index 4507624fd4a..4667ff6e8a8 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -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: