prod/ansible-prod/lib/python3.11/site-packages/ansible_collections/containers/podman/CONTRIBUTING.md

Contributing to the Podman Ansible Collection

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.

This document provides guidelines to help you get started. Please read it carefully to ensure a smooth and effective contribution process.

Code of Conduct

All contributors are expected to follow our Code of Conduct. Please make sure you are familiar with its contents.

How to Contribute

You can contribute in several ways:

• Reporting Bugs: If you find a bug, please open an issue and provide as much detail as possible, including your Podman version, Ansible version, the playbook you are using, and the full error output.
• Suggesting Enhancements: If you have an idea for a new feature or an improvement to an existing one, please open a feature request.
• Submitting Pull Requests: If you want to fix a bug or add a feature yourself, please follow the guidelines below.

Development Setup

1. Fork and Clone: Fork the repository on GitHub and clone your fork locally.

   git clone https://github.com/YOUR-USERNAME/ansible-podman-collections.git
   cd ansible-podman-collections
   

2. Set up a Virtual Environment: It's highly recommended to work in a Python virtual environment.

   python3 -m venv venv
   source venv/bin/activate
   

3. Install Dependencies: The collection's testing dependencies are listed in test-requirements.txt.

   pip install -r test-requirements.txt
   

Guidelines for Pull Requests

General Workflow

1. Create a new branch for your changes: git checkout -b my-feature-or-fix.
2. Make your changes. Follow the coding and testing guidelines below.
3. Commit your changes with a clear and descriptive message. See existing commit messages for style (git log --oneline).
4. Push your branch to your fork: git push origin my-feature-or-fix.
5. Open a pull request against the main branch of the original repository.

Fixing a Bug

1. If an issue for the bug doesn't already exist, please create one.
2. Ideally, add an integration test case to tests/integration/targets/ that reproduces the bug and fails before your fix.
3. Implement the code change that fixes the bug.
4. Run the tests to ensure your fix works and doesn't break anything else.
5. In your PR description, use the "Fixes #123" syntax to link it to the issue.

Adding a New Module

We have a script to help you scaffold a new module.

1. Define Module Variables: Copy contrib/my_module_template_vars.yaml and customize it with your new module's details (name, author, options, etc.).
2. Generate the Module: Run the contrib/generate_module.sh script. This will create a new module file in the contrib directory.
3. Place the Module: Move the generated file into plugins/modules/.
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/.
5. Document: Ensure the DOCUMENTATION, EXAMPLES, and RETURN sections are thorough and accurate. This is critical for users.
6. Add Tests: Create a new integration test role and a new CI workflow for your module (see below).

Testing Strategy

This collection uses three types of tests. All tests must pass before a PR can be merged.

1. Sanity Tests

These tests check for code style, syntax errors, and other common issues. Sanity tests must pass in pull requests in opder to merge.

• How to Run:

  bash contrib/ansible-lint.sh
  

• Guidelines:

  • This will install collection in /tmp directory and run ansible-test sanity in docker.
  • The maximum line length is 120 characters.

2. Unit Tests

Unit tests are for testing specific functions in isolation, often by mocking external dependencies. This is an area we are actively working to improve.

• Location: tests/unit/plugins/modules/

• How to Run:

  bash contrib/ansible-unit.sh
  

• Guidelines:

  • This will install collection in /tmp directory and run ansible-test unit tests.

3. Integration Tests

These are the most important tests in the collection. They run Ansible playbooks to test modules against a live Podman instance.

• Location: tests/integration/targets/

• Structure: Each subdirectory in targets is an Ansible role that tests a specific module or feature. The main logic is in tasks/main.yml.

• Adding a New Integration Test:

  1. Create a new directory (role) for your module: tests/integration/targets/my_new_module/tasks.

  2. Create a main.yml file inside that directory.

  3. Write Ansible tasks that execute your module and verify its behavior. Use the assert or fail modules to check for expected outcomes.

     - name: Run my_new_module
       my_new_module:
         name: test_container
         state: present
       register: result
     
     - name: Assert that the container was created
       assert:
         that:
           - result.changed
           - result.container.State.Status == "running"
     

• Running Locally: You can run a specific test role using ansible-playbook. This requires a working Podman installation.

• Create a testing playbook with your tests like:

  - hosts: all
    gather_facts: false
    tasks:
  
      - include_tasks: tests/integration/targets/my_new_module/tasks/main.yml
  
  

  Install the collection version you develop with:

  ansible-galaxy collection install -vvv --force .
  

  and then run the playbook it with:

  ansible-playbook -vv -i localhost, my_playbook.yml
  

Continuous Integration (CI)

We use GitHub Actions to run all our tests automatically.

Adding a CI Job for a New Module

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.

1. Go to the .github/workflows/ directory.

2. Create a new file named after your module, e.g., podman_my_new_module.yml.

3. Copy the content from an existing module workflow, like podman_export.yml, and adapt it. You only need to change a few lines:

   name: Podman my_new_module
   
   on:
     push:
       paths:
         - 'plugins/modules/podman_my_new_module.py'
         - 'tests/integration/targets/podman_my_new_module/**'
     pull_request:
       paths:
         - 'plugins/modules/podman_my_new_module.py'
         - 'tests/integration/targets/podman_my_new_module/**'
   
   jobs:
     test:
       uses: ./.github/workflows/reusable-module-test.yml
       with:
         module_name: podman_my_new_module  # The name of your test role
         display_name: "Podman my_new_module" # A friendly name for the job
   

4. Commit this new workflow file along with your module and test code.

Final Checklist for Pull Requests

Before you submit your PR, please make sure you have:

• Read this CONTRIBUTING.md guide.
• Added or updated tests for your changes.
• Run ansible-test sanity and fixed any issues.
• Ensured all CI checks are passing on your PR.
• Updated the DOCUMENTATION block in the module if you changed any parameters.

Thank you for your contribution!