ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-07-24 22:00:22 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Add docs describing some additional behaviors around modules (#33631)

Browse source 
* Add docs describing some additional behaviors around modules, to outline why generic modules will not be accepted

* Add/copy the generic module guidelines to developing_modules

* Edits for clarity

* Edits for clarity
This commit is contained in:
Matt Martz 2017-12-07 15:31:26 -05:00 • committed by GitHub
commit 2d2f288e77
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 16 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/docsite/rst/dev_guide/developing_modules.rst
View file

@ -53,6 +53,16 @@ For more information about action plugins, `read the action plugins documentatio
Check out the roles documentation `available here <http://docs.ansible.com/ansible/playbooks_reuse_roles.html#roles>`_.
5. Should you write multiple modules instead of one module?
The following guidelines will help you determine if your module attempts to do too much, and should likely be broken into several smaller modules.
* Modules should have a concise and well defined functionality. Basically, follow the UNIX philosophy of doing one thing well.
* Modules should not require that a user know all the underlying options of an api/tool to be used. For instance, if the legal values for a required module parameter cannot be documented, that's a sign that the module would be rejected.
* Modules should typically encompass much of the logic for interacting with a resource. A lightweight wrapper around an API that does not contain much logic would likely cause users to offload too much logic into a playbook, and for this reason the module would be rejected. Instead try creating multiple modules for interacting with smaller individual pieces of the API.
.. _developing_modules_all: