General Coding Guidelines for Grafana Modules

Note: This section is still under development

General Rules

• modules should include integration tests (test/integration/targets)

Idempotence

• modules should be idempotent -- calling with the same options should not result in any change
• there may be some exceptions, for instance passwords, when they can't be compared with existing passwords. When password option is not specified, it should be omitted in idempotence check. Specifying password should cause update.

How to implement idempotence?

The most robust approach is as follows:

1. query current_resource_state structure/dictionary
2. construct new_resource_state from input parameters
3. compare new_resource_state with current_resource_state
4. update current_resource_state with new_resource_state
5. use updated current_resource_state to call create or create_or_update function

Please note that currently no module is entirely using this approach. Points (4) and (5) are important in order to preserve properties of resource that was not created by Ansible module and may have some properties that are not supported by current version of the module.

Testing

Tests that need to be performed on every module

• create resource
• create resource again with the same parameters, make sure no change was recorded
• create resource again with different parameters, make sure proper changes were made and change was recorded
• delete resource, make sure change was recorded
• delete non-existing resource, make sure no change was recorder