Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
294 lines (215 loc) · 15.3 KB

CONTRIBUTING.md

File metadata and controls

294 lines (215 loc) · 15.3 KB
Raw

Contributing

We follow Ansible Code of Conduct in all our contributions and interactions within this repository. If you are stuck while developing a module, refer to our recommended reads from the Ansible docs.

Issue tracker

Whether you are looking for an opportunity to contribute or you found a bug and already know how to solve it, please go to the issue tracker. There you can find feature ideas to implement, reports about bugs to solve, or submit an issue to discuss your idea before implementing it which can help choose a right direction at the beginning of your work and potentially save a lot of time and effort. Also somebody may already have started discussing or working on implementing the same or a similar idea, so you can cooperate to create a better solution together.

Review pull requests

Look through currently open pull requests.

You can help by reviewing and testing them, since this collection currently lacks integration tests. Reviews and tests help us estimate the maturity of a pull request and increase the likelihood to merge its contents. Note that reviewing does not only mean code review, but also offering comments on new interfaces added to existing plugins/modules, interfaces of new plugins/modules, improving language (not everyone is a native English speaker), or testing bugfixes and new features!

Also, consider taking up a valuable, reviewed, but abandoned pull request which you could politely ask the original authors to complete yourself.

If you want to test a PR locally, refer to our testing guide for instructions on how do it quickly.

If you find any inconsistencies or places in this document which can be improved, feel free to raise an issue or pull request to fix it.

Opening pull requests

Wether you found a bug and want to fix it or you want to contribute a new module, please refer to these conventions:

  • Try committing your changes with an informative but short commit message.
  • Make sure your PR includes a changelog fragment.
    • You must not include a fragment for new modules or new plugins. Also you shouldn't include one for docs-only changes.
    • Please always include a link to the pull request itself, and if the PR is about an issue, also a link to the issue. Also make sure the fragment ends with a period, and begins with a lower-case letter after -. (Again, if you don't do this, we'll add suggestions to fix it, so don't worry too much :) )
  • Note that we lint and format the code with ruff. If your change does not match the expectations, CI will fail and your PR will not get merged. Continue reading this guide to find out how to lint and format your code.

You can also read the Ansible community's Quick-start development guide.

New modules or plugins

Creating new modules and plugins requires a bit more work than other Pull Requests.

  1. Please make sure that your new module or plugin is not already part of this collection. If it is already partly adressed, you might want to add the functionality there or discuss refactoring the functions in an issue.

  2. Please do not add more than one plugin/module in one PR, unless they are closely releated. That makes it easier for reviewers, and increases the chance that your PR will get merged. If you plan to contribute a group of plugins/modules (say, more than a module and a corresponding _info module), please mention that in the first PR.

  3. When creating a new module or plugin, please make sure that you follow various guidelines:

Formatting, linting and tests

We use ruff to maintain a baseline of code readability and quality. Please check out our ruff configuration to find out which formatting and rules are enforced.

To perform basic testing, you will most likely require the following packages:

  • antsibull-nox
  • nox
  • ruff
  • ansible
  • pre-commit (optional)

and ideally a container runtime, for example podman or docker.

The repository includes a pre-commit configuration (.pre-commit-config.yaml) which runs basic Ruff checks before each commit. Hooks are not active until you install them. After installing the pre-commit package, run pre-commit install. If you want to manually run the hooks before making a commit, you can use pre-commit run.

To immediately run all default tests (format, lint), install the dependencies and run nox. To run all unit/sanity tests, use nox -s ansible-test-units or nox -s ansible-test-sanity.

Codequality

The following commands show how to lint and format your code with nox:

# Run all configured formatters:
nox -Re formatters

# Lint:
nox -Re codeqa

# If you notice discrepancies between your local formatter and CI, you might
# need to re-generate the virtual environment:
nox -e formatters

While antsibull-nox and nox enable you to run the whole suite of tests, you may use ruff format and ruff check immediately within your development environment to perform basic linting and formatting. Note that while our CI is aware of changed files, your environment may not be. Thus, ruff errors, which might stem for other files, will not fail the tests of your contribution and can be ignored.

Sanity tests

The following commands show how to run ansible-test sanity tests:

# Run basic sanity tests for all files in the collection:
nox -Re ansible-test-sanity-devel

# Run basic sanity tests for the given files and directories:
nox -Re ansible-test-sanity-devel -- plugins/modules/system/pids.py tests/integration/targets/pids/

# Run all other sanity tests for all files in the collection:
nox -R

Unit tests

The following commands show how to run unit tests:

# Run all unit tests:
nox -Re ansible-test-units-devel

# Run all unit tests for one Python version (a lot faster):
nox -Re ansible-test-units-devel -- --python 3.13

# Run a specific unit test for one Python version:
nox -Re ansible-test-units-devel -- --python 3.13 tests/unit/plugins/modules/test_proxmox_kvm.py

Integration tests

Most Proxmox module integration tests require access to a real Proxmox environment and are marked as unsupported in CI. This means they are skipped during automated testing and must be executed manually in a properly configured environment.

Warning: Integration tests may create, modify, or delete resources on your Proxmox environment. It is strongly recommended to use a dedicated test environment.

Setup

  1. Create your local configuration file:

    cp tests/integration/integration_config.yml.template tests/integration/integration_config.yml

  2. Adjust the authentication variables to match your Proxmox environment. A minimal example configuration may look like:

    proxmox_host: https://your-proxmox:8006
proxmox_user: root@pam
proxmox_password: your-password
validate_certs: false

    Some modules require the root@pam user due to permission constraints.

Running tests

You can run integration tests using ansible-test:

# Run all integration tests
ansible-test integration -v --allow-unsupported

# Run all integration tests using Docker
ansible-test integration --docker -v --allow-unsupported

# Run a specific test target
ansible-test integration proxmox_pool -v --allow-unsupported

# Run a specific test target using Docker
ansible-test integration proxmox_pool --docker -v --allow-unsupported

Manual test and review of changes

If you want to test your new module or bugfix within a playbook, you may do the following:

  • Ensure your repository resides, for example, in exampledir/community/proxmox.
  • Set up Ansible to find your collection export ANSIBLE_COLLECTIONS_PATH="$HOME/exampledir". Alternatively, you may edit your ansible.cfg.
  • Verify, that your modified collection is found: ansible-galaxy collection list

Now you can use your custom code in playbooks and roles. And you can use ansible-doc to review your rendered documentation.

Helpful Documentation

Unless you already read it up above, you probably really shoudl check out these links: