New metadata 1.0 (#22587)

Changes to the metadata format were approved here:
https://github.com/ansible/proposals/issues/54
* Update documentation to the new metadata format
* Changes to metadata-tool to account for new metadata
  * Add GPL license header
  * Add upgrade subcommand to upgrade metadata version
  * Change default metadata to the new format
  * Fix exclusion of non-modules from the metadata report
* Fix ansible-doc for new module metadata
* Exclude metadata version from ansible-doc output
* Fix website docs generation for the new metadata
* Update metadata schema in valiate-modules test
* Update the metadata in all modules to the new version

2 files changed, 23 insertions, 21 deletions

diff --git a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst
index bb81898581..7c05546201 100644
--- a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst
+++ b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst
@@ -31,9 +31,9 @@ The following  checklist items are important guidelines for people who want to c
 
     ANSIBLE_METADATA = {'status': ['preview'],
                         'supported_by': 'community',
-                        'version': '1.0'}
+                        'metadata_version': '1.0'}
 
-The complete module metadata specification is here: https://github.com/ansible/proposals/issues/30
+The complete module metadata specification is here: https://docs.ansible.com/ansible/dev_guide/developing_modules_documenting.html#ansible-metadata-block
 
 * Documentation: Make sure it exists
     * Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience--readable both by experts and non-experts. This documentation is not meant to teach a total novice, but it also should not be reserved for the Illuminati (hard balance).
diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
index 1c719e6d53..f1c2dcc3b6 100644
--- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
+++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
@@ -33,23 +33,28 @@ All modules must have the following sections defined in this order:
 ANSIBLE_METADATA Block
 ----------------------
 
-ANSIBLE_METADATA contains information about the module for use by other tools. At the moment, it informs other tools which type of maintainer the module has and to what degree users can rely on a module's behaviour remaining the same over time.
+``ANSIBLE_METADATA`` contains information about the module for use by other tools. At the moment, it informs other tools which type of maintainer the module has and to what degree users can rely on a module's behaviour remaining the same over time.
 
 For new modules, the following block can be simply added into your module
 
 .. code-block:: python
 
-   ANSIBLE_METADATA = {'status': ['preview'],
-                       'supported_by': 'community',
-                       'version': '1.0'}
+   ANSIBLE_METADATA = {'metadata_version': '1.0',
+                       'status': ['preview'],
+                       'supported_by': 'community'}
 
-.. warning:: version field
+.. warning::
 
-   This is the version of the ``ANSIBLE_METADATA`` schema, *not* the version of the module.
+   * ``metadata_version`` is the version of the ``ANSIBLE_METADATA`` schema, *not* the version of the module.
+   * Promoting a module's ``status`` or ``supported_by`` status should only be done by members of the Ansible Core Team.
 
-.. warning::
+.. note:: Pre-released metdata version
 
-   Promoting a module's ``status`` or ``supported_by`` status should only be done by members of the Ansible Core Team.
+    During development of Ansible-2.3, modules had an initial version of the
+    metadata.  This version was modified slightly after release to fix some
+    points of confusion.  You may occassionally see PRs for modules where the
+    ANSIBLE_METADATA doesn't look quite right because of this.  Module
+    metadata should be fixed before checking it into the repository.
 
 Version 1.0 of the metadata
 +++++++++++++++++++++++++++
@@ -60,34 +65,31 @@ Structure
 .. code-block:: python
 
   ANSIBLE_METADATA = {
-      'version': '1.0',
-      'supported_by': 'core|community|unmaintained|committer',
-      'status': ['stableinterface|preview|deprecated|removed']
+      'metadata_version': '1.0',
+      'supported_by': 'community',
+      'status': ['preview', 'deprecated']
   }
 
 Fields
 ``````
 
-:version: An “X.Y” formatted string. X and Y are integers which
+:metadata_version: An “X.Y” formatted string. X and Y are integers which
    define the metadata format version. Modules shipped with Ansible are
    tied to an Ansible release, so we will only ship with a single version
    of the metadata. We’ll increment Y if we add fields or legal values
    to an existing field. We’ll increment X if we remove fields or values
    or change the type or meaning of a field.
 :supported_by: This field records who supports the module.
-   Default value is community. Values are:
+   Default value is ``community``. Values are:
 
    :core: Maintained by the Ansible core team. Core team will fix
       bugs, add new features, and review PRs.
    :community: This module is maintained by the community at large,
       which is responsible for fixing bugs, adding new features, and
       reviewing changes.
-   :unmaintained: This module currently needs a new community
-      contributor to help maintain it.
-   :committer: Committers to the Ansible repository are the
-      gatekeepers for this module. They will review PRs from the community
-      before merging but might not generate fixes and code for new features
-      on their own.
+   :curated: The Ansible Core Team is the gatekeeper for this module. They
+      will review PRs from the community before merging but might not generate
+      fixes and code for new features on their own.
 
 :status: This field records information about the module that is
    important to the end user. It’s a list of strings. The default value