Skip to content

Commit

Permalink
Overhaul READMEs.
Browse files Browse the repository at this point in the history
  • Loading branch information
@robin-checkmk
robin-checkmk committed Nov 27, 2023
1 parent f4c8e65 commit f0a44fe
Show file tree
Hide file tree
Showing 6 changed files with 96 additions and 88 deletions.
31 changes: 20 additions & 11 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,15 +34,15 @@ the functionality, [pull requests](#Pull-Requests) are appreciated.
### Submitting Issues

If you encounter any bugs or have ideas for improvements feel free to open an [issue](https://github.com/Checkmk/ansible-collection-checkmk.general/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) or even better a [pull request](#Pull-Requests).
Dedicated requirements will be added here as suitable.
Please use the existing templates, especially for bug reports, as that helps you
and us to gather the necessary information to tackle the issue efficiently.

### Pull Requests

Please open a [pull request](https://github.com/Checkmk/ansible-collection-checkmk.general/pulls?q=is%3Apr+is%3Aopen)
if you have something to contribute.
On pull request creation, checks will run and tell you,
if your changes work with the collection. If errors are detected, please try to
fix them and update your pull request accordingly.
against the `devel` branch, if you have something to contribute.
On pull request creation, checks will run and tell you, if your changes work with the collection.
If errors are detected, please try to fix them and update your pull request accordingly.
If you need help, do ask for it.
After submitting a PR, follow the instructions to sign the [CLA](https://github.com/Checkmk/checkmk/blob/master/doc/cla/cla_readme.md) as asked by the bot.

Expand All @@ -56,10 +56,9 @@ at the file `changelogs/template.yml`.

### Documentation

Documentation is still a work in progress.
Module documentation is compiled during a release and stored as `docs/module.rst`,
but this is not ideal yet. However, please use the inline documentation as seen
in the existing modules when creating additional modules.
Module documentation is compiled during a release and stored as `docs/module.rst`.
It also becomes available [in the Galaxy](https://galaxy.ansible.com/ui/repo/published/checkmk/general/docs/).
Please use the inline documentation as seen in the existing modules when creating additional modules.

## Style Guide

Expand All @@ -71,6 +70,7 @@ in the existing modules when creating additional modules.
* Write [good commit messages](https://chris.beams.io/posts/git-commit/)

### Plugins

In general, stick to Ansible coding best practices and look out for test gotchas.

**Module Options**
Expand All @@ -86,6 +86,7 @@ There are different approaches to the module options, depending on the nature of
It is possible to implement an alias for a module option. This should be used rather carefully to not clutter the options. However, they can be an option, if one is uncertain how to name an option, or to deprecate an option, before actually removing it. If in doubt, feel free to ask for review in your PR.

### Roles and Playbooks

The following are guidelines to keep in mind, when creating or changing roles and playbooks.
- Variables
- Use snake case (`snake_case_variable`)
Expand All @@ -98,10 +99,12 @@ The following are guidelines to keep in mind, when creating or changing roles an
- When tagging roles or playbooks, separate single words with dashes (`my-custom-tag`)

## Tests

We strive to provide the best possible quality with this collection, hence we have implemented tests, that verify different aspects of code quality.
We urge you to run the following tests locally as applicable, so the turnaround on your pull request ist as low as possible.
We urge you to run the following tests locally as applicable, so the turnaround on your pull request is as low as possible.

### Sanity

[Ansible Sanity Tests](https://docs.ansible.com/ansible/latest/dev_guide/testing_sanity.html) enforce Ansible coding standards and requirements facilitating static code analysis. The `ansible-test` tool typically comes along with your Ansible installation (e.g. if you use the `requirements.txt` of this project).
We recommend using the `--docker` option, so you get the best results, as that uses a Docker image crafted and maintained by the Ansible project.
**Caution**: By default, Docker containers cannot be run as an unprivileged user! Depending on your setup you need to allow your user to run containers, or run `ansible-test` with `sudo`. Keep in mind, that with the latter you are running in another environment and might need to take care of installing the Python requirements for Ansible.
Expand All @@ -110,11 +113,12 @@ To run the tests locally, use the following command in the project root:

ansible-test sanity --docker

You can also run a subset by mentioning them as follows. See `ansible-test sanity --list-tests` for available tests). We strongly recommend to run all tests though.
You can also run a subset by mentioning them as follows. See `ansible-test sanity --list-tests` for available tests. We strongly recommend to run all tests though.

ansible-test sanity $TEST_CASE --docker

### Integration

[Ansible Integration Tests](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html) run test cases created by the maintainers of this project, to ensure the collection actually does what is intended. The `ansible-test` tool typically comes along with your Ansible installation (e.g. if you use the `requirements.txt` of this project).
We strongly recommend using the `--docker` option, so you do not modify your local system with these tests.
**Caution**: By default, Docker containers cannot be run as an unprivileged user! Depending on your setup you need to allow your user to run containers, or run `ansible-test` with `sudo`. Keep in mind, that with the latter you are running in another environment and might need to take care of installing the Python requirements for Ansible.
Expand All @@ -128,16 +132,19 @@ You can also run a subset by mentioning them as follows. See `tests/integration/
ansible-test integration $TEST_CASE --docker

### Molecule

To test our roles, we use [Molecule](https://www.jeffgeerling.com/blog/2018/testing-your-ansible-roles-molecule). It can be installed using the `requirements.txt`in this project or manually. The tests are crafted by the maintainers of this project to reflect real world scenarios a role would be used in. To run the tests, you need to navigate to the role directory and choose a scenario. At the time of writing those are named after the supported Checkmk versions: `2.1.0`and `2.2.0`.

cd roles/server/
molecule test -s 2.1.0
molecule test -s 2.2.0

### Unit

There are currently no unit tests.

## Releasing this collection

Releasing this collection is automated using GitHub Actions.
Before running the action `Release Collection` against the `main` branch, the
following needs to be done:
Expand All @@ -155,8 +162,10 @@ Some of these steps can already be checked and done with `scripts/release.sh`. T
You should definitely check the resulting changes thoroughly before committing.

## Code of Conduct

See [Code of Conduct](CODE_OF_CONDUCT.md).

## Forum

If you have questions, feedback and or simply no Github account feel free to
reach out to our awesome [Checkmk Community (using the 'ansible' tag)](https://forum.checkmk.com/tag/ansible).
29 changes: 13 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,15 @@
# Checkmk Ansible Collection

Checkmk already provides the needed APIs to automate and
configure your monitoring. With this project we want to create
and share modules and roles for Ansible to both simplify your first steps
with automating Checkmk and keep your daily operations smooth and efficient.

---
Checkmk already provides the needed APIs to automate and configure your monitoring.
With this project we want to augment the experience and provide easy to use
modules and roles for Ansible to both simplify your first steps with automating
Checkmk and keep your daily operations smooth and efficient.

## Here be dragons!

This repository is provided as is and we cannot guarantee stability at this point.
This collection is provided AS IS and we cannot guarantee proper functionality.
Additionally, there is no commercial support whatsoever!
This is an open source endeavour, which we want to share and progress with the community.
This is an open source endeavour, on which we want to collaborate with the community.

[![Ansible Sanity Tests](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ansible-sanity-tests.yaml/badge.svg)](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ansible-sanity-tests.yaml)
<!-- [![Ansible Unit Tests](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ansible-unit-tests.yaml/badge.svg)](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ansible-unit-tests.yaml) -->
Expand All @@ -32,15 +30,10 @@ or run the following command substituting the `$MODULE_NAME`:

For any form of support queries or requests refer to [SUPPORT.md](SUPPORT.md).

## Repository Structure

For information about the structure and organization of this repository
have a look at [STRUCTURE.md](docs/STRUCTURE.md).

You can find playbooks, demonstrating several aspects of this collection in the folder [playbooks/demo/](playbooks/demo/).

## Included content

You can find playbooks, demonstrating the content of this collection in the folder [playbooks/demo/](playbooks/demo/).

<!--start collection content-->
<!-- ### Inventory plugins
Name | Description
Expand All @@ -49,6 +42,7 @@ Name | Description
-->

### Lookup plugins

Name | Description | Tests
--- | --- | ---
[checkmk.general.folder](https://github.com/Checkmk/ansible-collection-checkmk.general/blob/main/plugins/lookup/folder.py)|Look up folder attributes.|[![Integration Tests for Folder Lookup Module](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ans-int-test-lkp-folder.yaml/badge.svg)](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ans-int-test-lkp-folder.yaml)
Expand All @@ -58,6 +52,7 @@ Name | Description | Tests
[checkmk.general.version](https://github.com/Checkmk/ansible-collection-checkmk.general/blob/main/plugins/lookup/version.py)|Look up version and edition information.|[![Integration Tests for Version Lookup Module](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ans-int-test-lkp-version.yaml/badge.svg)](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ans-int-test-lkp-version.yaml)

### Modules

Name | Description | Tests
--- | --- | ---
[checkmk.general.activation](https://github.com/Checkmk/ansible-collection-checkmk.general/blob/main/plugins/modules/activation.py)|Activate changes.|[![Integration Tests for Activation Module](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ans-int-test-activation.yaml/badge.svg)](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ans-int-test-activation.yaml)
Expand All @@ -74,6 +69,7 @@ Name | Description | Tests
[checkmk.general.user](https://github.com/Checkmk/ansible-collection-checkmk.general/blob/main/plugins/modules/user.py)|Manage users.|[![Integration Tests for User Module](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ans-int-test-user.yaml/badge.svg)](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/ans-int-test-user.yaml)

### Roles

Name | Description | Tests
--- | --- | ---
[checkmk.general.agent](https://github.com/Checkmk/ansible-collection-checkmk.general/blob/main/roles/agent/README.md)|Installs Checkmk agents.| [![Molecule Tests for Agent Role](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/molecule-role-agent.yaml/badge.svg)](https://github.com/Checkmk/ansible-collection-checkmk.general/actions/workflows/molecule-role-agent.yaml)
Expand Down Expand Up @@ -126,7 +122,7 @@ if you list the `checkmk.general` collection in the playbook's [`collections`](h
See [CONTRIBUTING](CONTRIBUTING.md).
## Release notes
<!--Add a link to a changelog.rst file or an external docsite to cover this information. -->
See [CHANGELOG.rst](CHANGELOG.rst).
## Roadmap
Expand All @@ -152,4 +148,5 @@ Please do **not** consider a concrete planning document!
- [Ansible Community code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html)
## Licensing
See [LICENSE](LICENSE).
7 changes: 4 additions & 3 deletions SECURITY.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Security Policy

## Disambiguation

This policy solely applies to the Checkmk Ansible Collection, not Checkmk itself!
For Checkmk itself, please refer to [this Vulnerability disclosure policy](https://checkmk.com/responsible-disclosure-policy)

Expand All @@ -11,9 +12,9 @@ Versions in this repository are used solely for stability, so your Ansible confi
does not break.
However, we cannot and will not support older versions, especially security-wise.
If you find a vulnerability, please report it as stated below,
and we will do our best to fix it in the next release.
and we will do our best to fix it as soon as possible.

## Reporting a Vulnerability

For now, please open a normal [issue](https://github.com/Checkmk/ansible-collection-checkmk.general/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) in the repository but try to disclose the
vulnerability as reasonable as possible.
For now, please open a normal [issue](https://github.com/Checkmk/ansible-collection-checkmk.general/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)
in the repository but try to disclose the vulnerability as reasonable as possible.
11 changes: 8 additions & 3 deletions SUPPORT.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,13 @@ Of course you can reach out in the [Checkmk Community (using the 'ansible' tag)]
or create [issues here](https://github.com/Checkmk/ansible-collection-checkmk.general/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc).

# Compatibility Matrix
The following is a compatibility overview between this collection and Checkmk. We always try to track the most recent Checkmk version. This table will give you an overview which collection versions were tested against which Checkmk versions.
There is of course no guarantees, that there will be no issues at all, but we do our best in testing. On the other hand this obviously does not limit the collection versions to the Checkmk versions mentioned here. Most likely the collection will work with most current Checkmk versions.

The following is a compatibility overview between this collection, Ansible and Checkmk.
We always try to track the most recent Ansible and Checkmk versions.
This table will give you an overview against which Ansible and Checkmk versions we tested a release.
There is of course no guarantees, that there will be no issues at all, but we do our best in testing.
On the other hand this obviously does not limit the collection versions to the Checkmk versions mentioned here.
Most likely the collection will work with most current Checkmk versions.

Collection Version | Checkmk Versions | Ansible Versions | Remarks
--- | --- | --- | ---
Expand Down Expand Up @@ -40,4 +45,4 @@ Collection Version | Checkmk Versions | Ansible Versions | Remarks
3.2.0 | 2.0.0p38, 2.1.0p32, 2.2.0p8 | 2.13, 2.14, 2.15 | None
3.3.0 | 2.0.0p39, 2.1.0p35, 2.2.0p12 | 2.13, 2.14, 2.15 | None
3.4.0 | 2.0.0p39, 2.1.0p36, 2.2.0p14 | 2.13, 2.14, 2.15 | None
4.0.0 | 2.0.0p39, 2.1.0p36, 2.2.0p14 | 2.14, 2.15, 2.16 | None
4.0.0 | 2.0.0p39, 2.1.0p36, 2.2.0p14 | 2.14, 2.15, 2.16 | Breaking changes to the following roles: `agent`, `server`.
Loading

0 comments on commit f0a44fe

Please sign in to comment.