Debian Codegraph @

ansible_collections/containers/podman/CONTRIBUTING.md

raw
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!