Add _info / _facts module related notes (#169)

* Add _info / _facts module related notes * Update collection_checklist.md Co-authored-by: Felix Fontein <[email protected]> * Update collection_requirements.rst Co-authored-by: Felix Fontein <[email protected]> * Update collection_checklist.md Co-authored-by: Amin Vakil <[email protected]> * Update collection_checklist.md Co-authored-by: Sandra McCann <[email protected]> * Update collection_checklist.md Co-authored-by: Jill R <[email protected]> * Update collection_requirements.rst Co-authored-by: Sandra McCann <[email protected]> * Update collection_requirements.rst Co-authored-by: Jill R <[email protected]> * Update collection_checklist.md Co-authored-by: Toshio Kuratomi <[email protected]> Co-authored-by: Felix Fontein <[email protected]> Co-authored-by: Amin Vakil <[email protected]> Co-authored-by: Sandra McCann <[email protected]> Co-authored-by: Jill R <[email protected]> Co-authored-by: Toshio Kuratomi <[email protected]>
ansible-collections · May 5, 2021 · a5426da · a5426da
1 parent f035a44
commit a5426da
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 1 deletion.
diff --git a/collection_checklist.md b/collection_checklist.md
@@ -15,7 +15,11 @@ Every comment should say whether the reviewer expects it to be addressed, or whe
 - [ ] adheres to [semantic versioning](https://semver.org/)
 - [ ] follows [licensing rules](https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#licensing)
 - [ ] follows the [Ansible documentation standards](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_documenting.html) and the [style guide](https://docs.ansible.com/ansible/devel/dev_guide/style_guide/index.html#style-guide)
-- [ ] follows [development conventions](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html)
+- [ ] follows [development conventions](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html); as well as these other requirements:
+  - [ ] modules that only gather information are named `<something>_info`
+  - [ ] modules that return `ansible_facts` are named `<something>_facts` and do not return non-facts
+  - [ ] other modules must not allow querying information using specific `state` option values, or similar mechanisms (like `state=get` or `state=query`).  These features should be moved to `<something>_info` or `<something>_fact` modules.
+  - [ ] `check_mode` is supported in all `_info` and `_facts` modules
 - [ ] supports Python 2.6 or greater and Python 3.5 or greater. If it does not, read the [full guidelines](https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#python-compatibility) to see if you qualify for an exception and document the unsupported [Python versions](https://docs.ansible.com/ansible/latest/dev_guide/developing_python_3.html#ansible-and-python-3) in the collection ``README.md`` and in every module and plugin (or in doc fragments)
 - [ ] only uses the [allowed plugin types](https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#modules-plugins) in the `plugins/` directory
 - [ ] has `README.md`

diff --git a/collection_requirements.rst b/collection_requirements.rst
@@ -198,6 +198,9 @@ Versioning and deprecation
 Naming
 ======
 
+Collection naming
+-----------------
+
 For collections under ansible-collections the repository SHOULD be named ``NAMESPACE.COLLECTION``.
 
 To create a new collection and corresponding repository, first, a new namespace in Galaxy has to be created via submitting `Request a namespace <https://github.com/ansible/galaxy/issues/new/choose>`_.
@@ -215,6 +218,11 @@ We should avoid FQCN / repository names:
 
 If your collection is planned to be certified on Automation Hub, please consult with Red Hat Partner Engineering to ensure collection naming compatibility between the community collection on **Galaxy**.
 
+Module naming
+-------------
+
+Modules that only gather information MUST be named ``<something>_info``. Modules that return ``ansible_facts`` are named ``<something>_facts`` and do not return non-facts.
+For more information, refer to the `Developing modules guidelines <https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_general.html#creating-an-info-or-a-facts-module>`_.
 
 Licensing
 =========
@@ -341,6 +349,15 @@ Also:
 
 See `Migrating content to a different collection <https://docs.ansible.com/ansible/devel/dev_guide/developing_collections.html#migrating-ansible-content-to-a-different-collection>`_ for complete details.
 
+Development conventions
+=======================
+
+Besides all the requirements listed in the `Development conventions <https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html>`_, be sure:
+
+* Your modules do not query information using special ``state`` option values like ``get``, ``list``, ``query``, or ``info`` -
+  create new ``_info`` or ``_facts`` modules instead (for more information, refer to the `Developing modules guidelines <https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_general.html#creating-an-info-or-a-facts-module>`_)
+* ``check_mode`` is supported in all ``*_info`` and ``*_facts`` modules (for more information, refer to the `Development conventions <https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html#following-ansible-conventions>`_)
+
 
 Requirements for collections to be included in the Ansible Package
 ==================================================================