From 2d2f288e77eeaf75fb37d833434b21b134fd0575 Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Thu, 7 Dec 2017 15:31:26 -0500 Subject: [PATCH] Add docs describing some additional behaviors around modules (#33631) * 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 --- docs/docsite/rst/dev_guide/developing_modules.rst | 10 ++++++++++ .../dev_guide/developing_modules_best_practices.rst | 7 ++++++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/dev_guide/developing_modules.rst b/docs/docsite/rst/dev_guide/developing_modules.rst index 92ff42e0f37..1f7cf44c410 100644 --- a/docs/docsite/rst/dev_guide/developing_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_modules.rst @@ -53,6 +53,16 @@ For more information about action plugins, `read the action plugins documentatio Check out the roles documentation `available here `_. +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: diff --git a/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst b/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst index 19f56e2fda9..74ac9bd8439 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst @@ -26,6 +26,11 @@ and guidelines: * As results from many hosts will be aggregated at once, modules should return only relevant output. Returning the entire contents of a log file is generally bad form. +* 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. .. _debugging_ansiblemodule_based_modules: @@ -190,4 +195,4 @@ Avoid creating a module that does the work of other modules; this leads to code Avoid creating 'caches'. Ansible is designed without a central server or authority, so you cannot guarantee it will not run with different permissions, options or locations. If you need a central authority, have it on top of Ansible (for example, using bastion/cm/ci server or tower); do not try to build it into modules. Always use the hacking/test-module script when developing modules and it will warn -you about these kind of things. \ No newline at end of file +you about these kind of things.