| 1 |
# Contributing to the Podman Ansible Collection |
| 2 |
|
| 3 |
First off, thank you for considering contributing to this collection! We welcome any help, from reporting a bug to submitting a new feature. Every contribution is valuable. |
| 4 |
|
| 5 |
This document provides guidelines to help you get started. Please read it carefully to ensure a smooth and effective contribution process. |
| 6 |
|
| 7 |
## Code of Conduct |
| 8 |
|
| 9 |
All contributors are expected to follow our [Code of Conduct](CODE-OF-CONDUCT.md). Please make sure you are familiar with its contents. |
| 10 |
|
| 11 |
## How to Contribute |
| 12 |
|
| 13 |
You can contribute in several ways: |
| 14 |
|
| 15 |
* **Reporting Bugs:** If you find a bug, please [open an issue](https://github.com/containers/ansible-podman-collections/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml) and provide as much detail as possible, including your Podman version, Ansible version, the playbook you are using, and the full error output. |
| 16 |
* **Suggesting Enhancements:** If you have an idea for a new feature or an improvement to an existing one, please [open a feature request](https://github.com/containers/ansible-podman-collections/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml). |
| 17 |
* **Submitting Pull Requests:** If you want to fix a bug or add a feature yourself, please follow the guidelines below. |
| 18 |
|
| 19 |
## Development Setup |
| 20 |
|
| 21 |
1. **Fork and Clone:** Fork the repository on GitHub and clone your fork locally. |
| 22 |
|
| 23 |
```bash |
| 24 |
git clone https://github.com/YOUR-USERNAME/ansible-podman-collections.git |
| 25 |
cd ansible-podman-collections |
| 26 |
``` |
| 27 |
|
| 28 |
2. **Set up a Virtual Environment:** It's highly recommended to work in a Python virtual environment. |
| 29 |
|
| 30 |
```bash |
| 31 |
python3 -m venv venv |
| 32 |
source venv/bin/activate |
| 33 |
``` |
| 34 |
|
| 35 |
3. **Install Dependencies:** The collection's testing dependencies are listed in `test-requirements.txt`. |
| 36 |
|
| 37 |
```bash |
| 38 |
pip install -r test-requirements.txt |
| 39 |
``` |
| 40 |
|
| 41 |
## Guidelines for Pull Requests |
| 42 |
|
| 43 |
### General Workflow |
| 44 |
|
| 45 |
1. Create a new branch for your changes: `git checkout -b my-feature-or-fix`. |
| 46 |
2. Make your changes. Follow the coding and testing guidelines below. |
| 47 |
3. Commit your changes with a clear and descriptive message. See existing commit messages for style (`git log --oneline`). |
| 48 |
4. Push your branch to your fork: `git push origin my-feature-or-fix`. |
| 49 |
5. Open a pull request against the `main` branch of the original repository. |
| 50 |
|
| 51 |
### Fixing a Bug |
| 52 |
|
| 53 |
1. If an issue for the bug doesn't already exist, please create one. |
| 54 |
2. Ideally, add an integration test case to `tests/integration/targets/` that reproduces the bug and fails before your fix. |
| 55 |
3. Implement the code change that fixes the bug. |
| 56 |
4. Run the tests to ensure your fix works and doesn't break anything else. |
| 57 |
5. In your PR description, use the "Fixes #123" syntax to link it to the issue. |
| 58 |
|
| 59 |
### Adding a New Module |
| 60 |
|
| 61 |
We have a script to help you scaffold a new module. |
| 62 |
|
| 63 |
1. **Define Module Variables:** Copy `contrib/my_module_template_vars.yaml` and customize it with your new module's details (name, author, options, etc.). |
| 64 |
2. **Generate the Module:** Run the `contrib/generate_module.sh` script. This will create a new module file in the `contrib` directory. |
| 65 |
3. **Place the Module:** Move the generated file into `plugins/modules/`. |
| 66 |
4. **Add Logic:** Implement the core logic for your module. If you need to share code with other modules, consider adding it to `plugins/module_utils/`. |
| 67 |
5. **Document:** Ensure the `DOCUMENTATION`, `EXAMPLES`, and `RETURN` sections are thorough and accurate. This is critical for users. |
| 68 |
6. **Add Tests:** Create a new integration test role and a new CI workflow for your module (see below). |
| 69 |
|
| 70 |
## Testing Strategy |
| 71 |
|
| 72 |
This collection uses three types of tests. All tests must pass before a PR can be merged. |
| 73 |
|
| 74 |
### 1. Sanity Tests |
| 75 |
|
| 76 |
These tests check for code style, syntax errors, and other common issues. Sanity tests must pass in pull requests in opder to merge. |
| 77 |
|
| 78 |
* **How to Run:** |
| 79 |
|
| 80 |
```bash |
| 81 |
bash contrib/ansible-lint.sh |
| 82 |
``` |
| 83 |
|
| 84 |
* **Guidelines:** |
| 85 |
* This will install collection in `/tmp` directory and run `ansible-test` sanity in docker. |
| 86 |
* The maximum line length is 120 characters. |
| 87 |
|
| 88 |
### 2. Unit Tests |
| 89 |
|
| 90 |
Unit tests are for testing specific functions in isolation, often by mocking external dependencies. This is an area we are actively working to improve. |
| 91 |
|
| 92 |
* **Location:** `tests/unit/plugins/modules/` |
| 93 |
* **How to Run:** |
| 94 |
|
| 95 |
```bash |
| 96 |
bash contrib/ansible-unit.sh |
| 97 |
``` |
| 98 |
|
| 99 |
* **Guidelines:** |
| 100 |
* This will install collection in `/tmp` directory and run `ansible-test` unit tests. |
| 101 |
|
| 102 |
### 3. Integration Tests |
| 103 |
|
| 104 |
These are the most important tests in the collection. They run Ansible playbooks to test modules against a live Podman instance. |
| 105 |
|
| 106 |
* **Location:** `tests/integration/targets/` |
| 107 |
* **Structure:** Each subdirectory in `targets` is an Ansible role that tests a specific module or feature. The main logic is in `tasks/main.yml`. |
| 108 |
|
| 109 |
* **Adding a New Integration Test:** |
| 110 |
1. Create a new directory (role) for your module: `tests/integration/targets/my_new_module/tasks`. |
| 111 |
2. Create a `main.yml` file inside that directory. |
| 112 |
3. Write Ansible tasks that execute your module and verify its behavior. Use the `assert` or `fail` modules to check for expected outcomes. |
| 113 |
|
| 114 |
```yaml |
| 115 |
- name: Run my_new_module |
| 116 |
my_new_module: |
| 117 |
name: test_container |
| 118 |
state: present |
| 119 |
register: result |
| 120 |
|
| 121 |
- name: Assert that the container was created |
| 122 |
assert: |
| 123 |
that: |
| 124 |
- result.changed |
| 125 |
- result.container.State.Status == "running" |
| 126 |
``` |
| 127 |
|
| 128 |
* **Running Locally:** You can run a specific test role using `ansible-playbook`. This requires a working Podman installation. |
| 129 |
* Create a testing playbook with your tests like: |
| 130 |
|
| 131 |
```yaml |
| 132 |
- hosts: all |
| 133 |
gather_facts: false |
| 134 |
tasks: |
| 135 |
|
| 136 |
- include_tasks: tests/integration/targets/my_new_module/tasks/main.yml |
| 137 |
|
| 138 |
``` |
| 139 |
|
| 140 |
Install the collection version you develop with: |
| 141 |
|
| 142 |
```bash |
| 143 |
ansible-galaxy collection install -vvv --force . |
| 144 |
``` |
| 145 |
|
| 146 |
and then run the playbook it with: |
| 147 |
|
| 148 |
```bash |
| 149 |
ansible-playbook -vv -i localhost, my_playbook.yml |
| 150 |
``` |
| 151 |
|
| 152 |
## Continuous Integration (CI) |
| 153 |
|
| 154 |
We use GitHub Actions to run all our tests automatically. |
| 155 |
|
| 156 |
### Adding a CI Job for a New Module |
| 157 |
|
| 158 |
To ensure your new module is tested on every PR, you must add a new workflow file. We use a reusable workflow to make this easy. |
| 159 |
|
| 160 |
1. Go to the `.github/workflows/` directory. |
| 161 |
2. Create a new file named after your module, e.g., `podman_my_new_module.yml`. |
| 162 |
3. Copy the content from an existing module workflow, like `podman_export.yml`, and adapt it. You only need to change a few lines: |
| 163 |
|
| 164 |
```yaml |
| 165 |
name: Podman my_new_module |
| 166 |
|
| 167 |
on: |
| 168 |
push: |
| 169 |
paths: |
| 170 |
- 'plugins/modules/podman_my_new_module.py' |
| 171 |
- 'tests/integration/targets/podman_my_new_module/**' |
| 172 |
pull_request: |
| 173 |
paths: |
| 174 |
- 'plugins/modules/podman_my_new_module.py' |
| 175 |
- 'tests/integration/targets/podman_my_new_module/**' |
| 176 |
|
| 177 |
jobs: |
| 178 |
test: |
| 179 |
uses: ./.github/workflows/reusable-module-test.yml |
| 180 |
with: |
| 181 |
module_name: podman_my_new_module # The name of your test role |
| 182 |
display_name: "Podman my_new_module" # A friendly name for the job |
| 183 |
``` |
| 184 |
|
| 185 |
4. Commit this new workflow file along with your module and test code. |
| 186 |
|
| 187 |
## Final Checklist for Pull Requests |
| 188 |
|
| 189 |
Before you submit your PR, please make sure you have: |
| 190 |
|
| 191 |
* [ ] Read this `CONTRIBUTING.md` guide. |
| 192 |
* [ ] Added or updated tests for your changes. |
| 193 |
* [ ] Run `ansible-test sanity` and fixed any issues. |
| 194 |
* [ ] Ensured all CI checks are passing on your PR. |
| 195 |
* [ ] Updated the `DOCUMENTATION` block in the module if you changed any parameters. |
| 196 |
|
| 197 |
Thank you for your contribution! |