Short high level description. Max 5 sentences for high level understanding purpose of the asset. No technical details!
- Describe ALL variables which consumer can use.
- Describe (in the column "Comments") how the variable influents behaviour of the Ansible Role. In the case of complex/long description, put it into subchapter of the chapter Procedure and put link to mentioned subchapter
- Put variables in alphabetical order
- If it makes STRONG sense you can split list of variables to more tables.
- To have clarity which variables are mandatory and which optional
- Show default value (if exists)
- Show expected units (kB, MB, seconds, ….)
- Show simplified types (String, Number, Integer, Boolean, Array, Dictionary)
- In case of Enumerated type - describe all accepted options and their meaning in the column "Comments"
- In case of structured variable (Array, Dictionaty) create separate
README_variable_name.mdwith description meaning of the structure and examples of structured values. THis file must be linked from "Comment" column
| Variable | Default | Comments |
|---|---|---|
| variable1 (type) | default value | Mandatory Description of the variable |
| variable2 (type) | default value | Description of the variable |
| variable3 (type) | default value | Description of the variable |
| ... | ... | ... |
List and description of all states (represented by unique Return Codes) where Ansible Role can finish of its execution. See documentation for Return Code Building Block
| Return Code Group | Return Code | Comments |
|---|---|---|
String value set to variable rc_group |
Integer value set to variable rc_number |
Description of meaning of given return code |
String value set to variable rc_group |
Integer value set to variable rc_number |
Description of meaning of given return code |
| ... | ... | ... |
Detailed description what automaton does. If needed to create subchapters for description meaning of specific "complex" variables
Information how to submit issue, what is a governance, who are main contacts, what is email task ID or Slack Channel for communication, ... If some information are common for more assets at once - maintain them centrally and put here link Generally see 12 factors to measuring an open source project's health following sections from the document should be reflected in this chapter:
- Project life cycle
- Governance
- Project leads
- Goals and roadmap
- Onboarding processes
- Outreach
- In the case of Ansible Collection - detailed description how the asset should be deployed into "framework":
- How to configure Ansible Tower Project and Job Template. Instructions must be in accordance of CACF Ansible Tower Object Naming Standards!
- In the case of Ansible Role which is plugable to specific Ansible Framework - this chapter must contain link to General Deployment Instructions for given Framework. For example:
- In the case of Ansible Role which is intended for specific Ansible Collection only, this chapter must contain link to this Collection.
- In the case of Ansible Role is Generic Reusable "component" and can be used in whatever another Ansible Collections - this chapter must contain reference to chapter Examples where must be commented pieces of code which demonstrate how to incorporate Ansible Role to another solution. Typical examples of Generic Reusable "component" are Building Blocks.
- Description of all limitations and known problems.
- Which platforms are or are not supported
- ...
- Description of environment and prerequisites which are needed for correct functionality of the Ansible Role.
- Example how to use Ansible Role in a Playbook