metadata 1.1

* Add network value to support_by field. * New support_by value, certified * Deprecate curated in favor of certified * Add conversion from 1.0 to 1.1 to metadata-tool * Add supported by Red Hat field to ansible-doc output
2026-05-06 21:32:49 +00:00 · 2017-08-05 11:28:21 -07:00
parent d50d65d448
commit af2073d057
19 changed files with 175 additions and 71 deletions
--- a/docs/bin/plugin_formatter.py
+++ b/docs/bin/plugin_formatter.py
@@ -255,9 +255,6 @@ def process_module(module, options, env, template, outputname, module_map, alias
    if doc is None:
        sys.exit("*** ERROR: MODULE MISSING DOCUMENTATION: %s, %s ***\n" % (fname, module))

-    if metadata is None:
-        sys.exit("*** ERROR: MODULE MISSING METADATA: %s, %s ***\n" % (fname, module))
-
    if deprecated and 'deprecated' not in doc:
        sys.exit("*** ERROR: DEPRECATED MODULE MISSING 'deprecated' DOCUMENTATION: %s, %s ***\n" % (fname, module))

--- a/docs/docsite/rst/dev_guide/developing_modules_checklist.rst
+++ b/docs/docsite/rst/dev_guide/developing_modules_checklist.rst
@@ -31,7 +31,7 @@ The following  checklist items are important guidelines for people who want to c

    ANSIBLE_METADATA = {'status': ['preview'],
                        'supported_by': 'community',
-                        'metadata_version': '1.0'}
+                        'metadata_version': '1.1'}

 The complete module metadata specification is here: `Ansible metadata block <https://docs.ansible.com/ansible/dev_guide/developing_modules_documenting.html#ansible-metadata-block>`_

--- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
+++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
@@ -75,7 +75,7 @@ For new modules, the following block can be simply added into your module

 .. code-block:: python

-   ANSIBLE_METADATA = {'metadata_version': '1.0',
+   ANSIBLE_METADATA = {'metadata_version': '1.1',
                       'status': ['preview'],
                       'supported_by': 'community'}

@@ -92,7 +92,7 @@ For new modules, the following block can be simply added into your module
    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
+Version 1.1 of the metadata
 +++++++++++++++++++++++++++

 Structure
@@ -101,7 +101,7 @@ Structure
 .. code-block:: python

  ANSIBLE_METADATA = {
-      'metadata_version': '1.0',
+      'metadata_version': '1.1',
      'supported_by': 'community',
      'status': ['preview', 'deprecated']
  }
@@ -115,13 +115,17 @@ Fields
   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.
+   Current metadata_version is "1.1"
 :supported_by: This field records who supports the module.
   Default value is ``community``. Values are:

-   :core:
-   :curated:
-   :community:
-   
+   * core
+   * network
+   * certfied
+   * community
+   * curated (Deprecated.  Modules in this category should probably be core or
+     certified instead)
+
   For information on what the support level values entail, please see
   `Modules Support <http://docs.ansible.com/ansible/modules_support.html>`_.

@@ -142,6 +146,18 @@ Fields
      kept so that documentation can be built. The documentation helps
      users port from the removed module to new modules.

+Changes from Version 1.0
++++++++++++++++++++++++
+
+:metadata_version: Version updated from 1.0 to 1.1
+:supported_by: All substantive changes were to potential values of the supported_by field
+
+  * Added the certified value
+  * Deprecated the curated value, modules shipped with Ansible will use
+    certified instead.  Third party modules are encouraged not to use this as
+    it is meaningless within Ansible proper.
+  * Added the network value
+
 DOCUMENTATION Block
 -------------------

--- a/docs/docsite/rst/dev_guide/developing_modules_general.rst
+++ b/docs/docsite/rst/dev_guide/developing_modules_general.rst
@@ -56,9 +56,9 @@ working on a whole new file. Here is an example:
    #!/usr/bin/python

    ANSIBLE_METADATA = {
-        'metadata_version': '1.0',
+        'metadata_version': '1.1',
        'status': ['preview'],
-        'supported_by': 'curated'
+        'supported_by': 'community'
    }

    DOCUMENTATION = '''
--- a/docs/docsite/rst/dev_guide/developing_modules_general_OLD.rst
+++ b/docs/docsite/rst/dev_guide/developing_modules_general_OLD.rst
@@ -88,9 +88,9 @@ working on a whole new file. Here is an example:
    #!/usr/bin/python

    ANSIBLE_METADATA = {
-        'metadata_version': '1.0',
+        'metadata_version': '1.1',
        'status': ['preview'],
-        'supported_by': 'curated'
+        'supported_by': 'community'
    }

    DOCUMENTATION = '''
@@ -401,9 +401,9 @@ working on a whole new file. Here is an example:
    #!/usr/bin/python

    ANSIBLE_METADATA = {
-        'metadata_version': '1.0',
+        'metadata_version': '1.1',
        'status': ['preview'],
-        'supported_by': 'curated'
+        'supported_by': 'community'
    }

    DOCUMENTATION = '''
@@ -714,9 +714,9 @@ working on a whole new file. Here is an example:
    #!/usr/bin/python

    ANSIBLE_METADATA = {
-        'metadata_version': '1.0',
+        'metadata_version': '1.1',
        'status': ['preview'],
-        'supported_by': 'curated'
+        'supported_by': 'community'
    }

    DOCUMENTATION = '''
@@ -1027,9 +1027,9 @@ working on a whole new file. Here is an example:
    #!/usr/bin/python

    ANSIBLE_METADATA = {
-        'metadata_version': '1.0',
+        'metadata_version': '1.1',
        'status': ['preview'],
-        'supported_by': 'curated'
+        'supported_by': 'community'
    }

    DOCUMENTATION = '''
@@ -1340,9 +1340,9 @@ working on a whole new file. Here is an example:
    #!/usr/bin/python

    ANSIBLE_METADATA = {
-        'metadata_version': '1.0',
+        'metadata_version': '1.1',
        'status': ['preview'],
-        'supported_by': 'curated'
+        'supported_by': 'community'
    }

    DOCUMENTATION = '''
@@ -1569,4 +1569,4 @@ Credit
 ======

 A *huge* thank you to the Ansible team at Red Hat for providing not only
-a great product but also the willingness to help out contributors!
+a great product but also the willingness to help out contributors!
--- a/docs/docsite/rst/modules_support.rst
+++ b/docs/docsite/rst/modules_support.rst
@@ -18,15 +18,21 @@ The modules are hosted on GitHub in a subdirectory of the `ansible <https://gith
 Core
 ````

-These are modules that the core ansible team maintains and will always ship with ansible itself.
+These are modules that the Ansible Core Team maintains and will always ship with Ansible itself.
 They will also receive slightly higher priority for all requests. Non-core modules are still fully usable.

-Curated
+Network
 ```````

-Some examples of Curated modules are submitted by other companies or maintained by the community. Maintainers of these types of modules must watch for any issues reported or pull requests raised against the module.
+These modules are supported by the Ansible Network Team in a relationship
+similar to how the Ansible Core Team maintains the Core modules.

-Core Committers will review all modules becoming Curated.  Core Committers will review proposed changes to existing Curated modules once the community maintainers of the module have approved the changes. Core committers will also ensure that any issues that arise due to Ansible engine changes will be remediated.
+Certified
+`````````
+
+Some examples of Certified modules are those submitted by other companies. Maintainers of these types of modules must watch for any issues reported or pull requests raised against the module.
+
+Core Committers will review all modules becoming Certified.  Core Committers will review proposed changes to existing Certified modules once the community maintainers of the module have approved the changes. Core committers will also ensure that any issues that arise due to Ansible engine changes will be remediated.
 Also, it is strongly recommended (but not presently required) for these types of modules to have unit tests.

 These modules are currently shipped with Ansible, but might be shipped separately in the future.
--- a/docs/templates/plugin.rst.j2
+++ b/docs/templates/plugin.rst.j2
@@ -207,7 +207,7 @@ Notes
 {% endif %}

 {% if not deprecated %}
-{% set support = { 'core': 'This module is maintained by those with core commit privileges', 'curated': 'This module is supported mainly by the community and is curated by core committers.', 'community': 'This module is community maintained without core committer oversight.'} %}
+{% set support = { 'core': 'The Ansible Core Team', 'network': 'The Ansible Network Team', 'certified': 'an Ansible Partner', 'community': 'The Ansible Community', 'curated': 'A Third Party'} %}
 {% set module_states = { 'preview': 'it is not guaranteed to have a backwards compatible interface', 'stableinterface': 'the maintainers for this module guarantee that no backward incompatible interface changes will be made'} %}

 {% if metadata %}
@@ -223,10 +223,10 @@ This module is flagged as **@{cur_state}@** which means that @{module_states[cur

 {% if metadata.supported_by %}

-Support
-~~~~~~~
+Support Level
+~~~~~~~~~~~~~

-@{ support[metadata.supported_by] }@
+This module is maintained by @{ support[metadata.supported_by] }@

 For more information on what this means please read :doc:`modules_support`