Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add "idempotence check" section to module docs #21299

Closed
lorin opened this issue Feb 11, 2017 · 5 comments
Closed

Add "idempotence check" section to module docs #21299

lorin opened this issue Feb 11, 2017 · 5 comments

Comments

@lorin
Copy link
Member

@lorin lorin commented Feb 11, 2017

ISSUE TYPE
  • Feature Idea
COMPONENT NAME

Documentation generated by modules

ANSIBLE VERSION
ansible 2.2.1.0
  config file =
  configured module search path = Default w/o overrides
CONFIGURATION

N/A

OS / ENVIRONMENT

N/A

SUMMARY

Add a section to module documentation that describes how the idempotence check is implemented.

STEPS TO REPRODUCE

For many modules, the logic used to implement the idempotence check isn't obvious. For example, the ec2_vpc_route_table module isn't idempotent if you don't specify tags. This information is present in the docs, in the description of the "lookup" option, but I missed it at first because I didn't read the documentation of every single option.

I think it would improve the usability of the module documentation if there was a separate "Idempotence check" section, just like there is currently an "Examples" and "Return values" section. Module authors can then specify explicitly how they are implementing the check.

@ansibot

This comment has been minimized.

Copy link
Contributor

@ansibot ansibot commented Feb 11, 2017

@dagwieers

This comment has been minimized.

Copy link
Member

@dagwieers dagwieers commented Feb 13, 2017

Ideally the idempotency check must only be enabled if integration tests exist to check idempotency.

@ansibot

This comment has been minimized.

Copy link
Contributor

@ansibot ansibot commented Sep 1, 2017

@ansibot

This comment has been minimized.

Copy link
Contributor

@ansibot ansibot commented Sep 13, 2017

@samdoran

This comment has been minimized.

Copy link
Member

@samdoran samdoran commented Aug 2, 2019

This is a good idea, but adding a specific section globally to all modules to accommodate the few very complex modules is overkill. This would also further complicate the documentation section of modules, which we do not want to do.

A complex explanation like this is bette suited to a README file in a collection.

To discuss this further, please reach out on IRC or the mailing list:

   * IRC: #ansible on irc.freenode.net  
   * mailing list: https://groups.google.com/forum/#!forum/ansible-project

@samdoran samdoran closed this Aug 2, 2019
@ansible ansible locked and limited conversation to collaborators Aug 30, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
5 participants
You can’t perform that action at this time.