1# Contribution guidelines
2
3**Table of contents**
4
5- [Contribution guidelines](#contribution-guidelines)
6  * [Contributing](#contributing)
7  * [Coding guidelines](#coding-guidelines)
8    + [Zabbix roles](#zabbix-roles)
9    + [Zabbix modules](#zabbix-modules)
10  * [Testing and Development](#testing-and-development)
11    + [Testing Zabbix roles](#testing-zabbix-roles)
12    + [Testing Zabbix modules](#testing-zabbix-modules)
13- [Additional information](#additional-information)
14  * [Virtualenv](#virtualenv)
15  * [Links](#links)
16
17Thank you very much for taking time to improve this Ansible collection. We appreciate your every contribution. Please make sure you are familiar with the content presented in this document to avoid any delays during reviews or merge.
18
19Please note that this project is released with following codes of conduct and by participating in the project you agree to abide by them:
20* [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md)
21* [Community Code of Conduct](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html)
22
23If you are interested in joining us as a maintainer, please open an issue.
24
25## Contributing
26
271. Fork this repository with community Zabbix collection.
282. Create a new branch and apply your changes to it. In addition to that:
29    1. Ensure that any changes you introduce to this collection are reflected in the documentation.
30    2. Ensure that your PR contains valid [changelog fragment](https://docs.ansible.com/ansible/devel/community/development_process.html#changelogs).
31    3. Include tests with your contribution to ensure that future pull requests will not break your functionality.
32    4. Make sure that tests succeed.
333. Push the branch to your forked repository.
344. Submit a new pull request into this collection.
35
36*Notes:*
37* Pull requests that fail during the tests will not be merged. If you have trouble narrowing down cause of a failure and would like some help, do not hesitate to ask for it in comments.
38* If you plan to propose an extensive feature or breaking change, please open an issue first. This allows collection maintainers to comment on such change in advance and avoid possible rejection of such contribution.
39
40## Coding guidelines
41
42Style guides are important because they ensure consistency in the content, look, and feel of a book or a website. Any contributions to this collection must adhere to the following rules:
43
44* [Ansible style guide](http://docs.ansible.com/ansible/latest/dev_guide/style_guide/).
45* Use "Ansible" when referring to the product and ``ansible`` when referring to the command line tool, package and so on.
46
47### Zabbix roles
48
49* Playbooks should be written in multi-line YAML format using ``key: value``.
50  * The form ``key=value`` is suitable for ``ansible`` ad-hoc execution, not for ``ansible-playbook``.
51* Every task should always have a ``name:`` keyword associated with it.
52
53### Zabbix modules
54
55These rules are required for any contributions proposing a new Zabbix module or updating an existing one. Modules should:
56
57* Be compatible with [currently supported Zabbix releases](https://www.zabbix.com/life_cycle_and_release_policy).
58* Include the same set of general options as other Zabbix modules:
59  * In `DOCUMENTATION` block via `extends_documentation_fragment` keyword.
60  * In module `argument_spec` as a set of module parameters.
61* Implement proper logout mechanism as other modules do.
62* Use the same version of `zabbix-api` library as defined in collection requirements.
63* Comply with [Ansible module best practices](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html).
64
65## Testing and Development
66
67It is recommended to use Docker for the testing as this repository is utilizing it for its own CI. Read [Docker installation guide](https://docs.docker.com/install/) for more information.
68
69Make sure you start your work on the current state of the repository with `main` branch up to date. The best way to both try new changes and run shipped tests is by cloning the repository to Ansible project:
70
71```bash
72cd <ANSIBLE-PROJECT>/
73mkdir -p collections/ansible_collections/community
74git clone git@github.com:<USERNAME>/community.zabbix.git collections/ansible_collections/community/zabbix
75```
76
77Functionality can be verified by looking at the documentation of a module:
78```bash
79ansible-doc community.zabbix.zabbix_host
80```
81
82Once this is done, you can reference modules and roles from testing playbook likes this:
83
84```yaml
85- hosts: myserver
86  roles:
87    - role: community.zabbix.zabbix_agent
88      zabbix_agent_server: 10.0.0.1
89      ...
90
91  tasks:
92    - name: Configure Zabbix host
93      community.zabbix.zabbix_host:
94        server_url: http://10.0.0.1/
95        ...
96      delegate_to: localhost
97```
98
99### Testing Zabbix roles
100
101*This section is subject to change as our CI regarding roles is being reworked and may not work for you right now!*
102
103Roles make use of [Molecule](https://molecule.readthedocs.io/en/latest/) to verify and test the execution of each role. In order to start testing with Molecule, you need to install the required dependencies. Requirements file can be found in the root of the [dj-wasabi/ansible-ci-base](https://github.com/dj-wasabi/ansible-ci-base) repository.
104
105It is recommended to create a [new Python virtual environment](#virtualenv) for this to not clutter your global Python installation. First, install the dependencies:
106
107```bash
108pip install -r requirements.txt
109```
110
111Note that Docker is required when testing roles as Molecule is configured to use it. Once everything is installed, validate your role changes with:
112
113```bash
114molecule test
115```
116
117### Testing Zabbix modules
118
119Modules are tested via `ansible-test` command. Configurations for integration and sanity tests for the command are contained within `tests` directory. Refer to the [official documentation](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html) for introduction to module integration testing within Ansible. Please note that this may fail if you get your directory structure wrong. If this happens, please see the start of [Testing and Development](#testing-and-development) regarding the placement of the collection.
120
121Running test suites locally requires a few dependencies to be installed. Same as for the roles, it is recommended to use [Python virtual environment](#virtualenv):
122
123```bash
124pip install docker-compose zabbix-api
125```
126
127Integration test suite for modules can be run with the commands below:
128
129```bash
130export zabbix_version=X.Y
131docker-compose up -d
132ansible-test integration -v --color --retry-on-error --continue-on-error --diff
133docker-compose down
134```
135*Notes*:
136* `zabbix_version=X.Y` will be expanded to Docker image `ubuntu-X.Y-latest`
137* Details for both variables and values that are in use can be read from [ansible-test.yml](.github/workflows/ansible-test.yml).
138
139Sanity test suite for the modules can be run with the commands:
140
141```bash
142ansible-test sanity -v --color --docker --python 3.6
143```
144
145# Additional information
146
147## Virtualenv
148
149It is recommended to use virtualenv for development and testing work to prevent any conflicting dependencies with other projects.
150
151A few resources describing virtualenvs:
152
153* http://thepythonguru.com/python-virtualenv-guide/
154* https://realpython.com/python-virtual-environments-a-primer/
155* https://www.dabapps.com/blog/introduction-to-pip-and-virtualenv-python/
156
157## Links
158
159* [Ansible](https://www.ansible.com/)
160* [Ansible style guide](http://docs.ansible.com/ansible/latest/dev_guide/style_guide/)
161* [Ansible module best practices](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_best_practices.html)
162* [Integration testing with `ansible-test`](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html)
163* [Docker installation guide](https://docs.docker.com/install/)
164* [Molecule](https://molecule.readthedocs.io/)
165* [Molecule V2 with your own role](https://werner-dijkerman.nl/2017/09/05/using-molecule-v2-to-test-ansible-roles/)
166* [dj-wasabi/ansible-ci-base](https://github.com/dj-wasabi/ansible-ci-base)
167* [Current Zabbix releases](https://www.zabbix.com/life_cycle_and_release_policy)
168
169**End note**: Have fun making changes. If a feature helps you, others may find it useful as well and we will be happy to merge it.
170