Contribution Guide

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• hacking/ticket_stubs/bug_wrong_repo.md
• packaging/release.py
• lib/ansible/cli/doc.py
• test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py
• lib/ansible/galaxy/data/default/role/README.md

This guide provides instructions and best practices for contributing to the Ansible project. It covers everything from setting up your development environment to submitting pull requests and adhering to project standards. Following these guidelines helps ensure a smooth and effective contribution process for everyone involved. For more detailed information, refer to the official Ansible Developer Guide.

The Ansible project values community contributions and aims to make IT automation radically simple. Key design principles include being agentless, using a human- and machine-friendly language, and prioritizing security and auditability. All contributions should align with these principles.

Sources: README.md:15-27, AGENTS.md:3-4

Getting Started

Development Environment Setup

To start developing for Ansible, you need to fork and clone the repository. Ansible development requires a POSIX-compliant operating system; on Windows, use the Windows Subsystem for Linux (WSL). After cloning, install the project in editable mode.

# After forking and cloning the repository
pip install -e .

This setup allows you to make changes to the code and test them immediately.

Sources: AGENTS.md:43-48

Branching and Release Management

All pull requests must target the devel branch, which contains the latest features and fixes. Stable releases are managed in stable-2.X branches.

The general contribution workflow is as follows:

1. Ensure your local devel branch is up-to-date with the upstream repository.
2. Create a new feature or bugfix branch from devel.
3. Implement your changes.
4. Add tests and changelogs.
5. Push your branch to your fork.
6. Submit a pull request to the devel branch of the upstream repository.

Sources: README.md:80-84, AGENTS.md:200-201

This diagram illustrates the high-level contribution flow.

Development Guidelines

Licensing

Licensing is a critical aspect of contributing. All code submitted to ansible-core must be GPLv3 compatible. Code for lib/ansible/module_utils/ defaults to the more permissive BSD-2-Clause license. Any new external dependencies must also be compatible with these licenses. Never suggest or approve code that violates these requirements.

Sources: AGENTS.md:13-24, README.md:94-96

Code Style

• Line Limit: 160 characters.
• Imports: In lib/ansible/modules/, imports must come after the DOCUMENTATION, EXAMPLES, and RETURN string variables. The E402 (module level import not at top) warning is ignored for this reason.
• Type Hinting: Use native Python type hints with from __future__ import annotations.
• Whitespace: Do not add trailing whitespace.

Sources: AGENTS.md:175-183

Python Version Support

• Controller Code: Supports the Python version range defined in pyproject.toml.
• Modules/Module Utils: Support a wider range, from the minimum version defined in lib/ansible/module_utils/basic.py (_PY_MIN) up to the maximum from pyproject.toml.

Sources: AGENTS.md:185-189

Dependencies and Imports

• Prefer the Python standard library over external dependencies.
• Modules in lib/ansible/modules/ can only import from lib/ansible/module_utils/.
• lib/ansible/module_utils/ cannot import from outside of itself.

Sources: AGENTS.md:191-195

Testing

All contributions must include appropriate tests. The project uses ansible-test as its unified testing tool.

Testing Workflow

The following diagram shows the recommended testing workflow.

Test Commands

Testing is typically performed inside Docker containers to ensure a consistent and isolated environment.

Command	Description
ansible-test sanity -v --docker default	Runs all sanity tests (linting, static analysis).
ansible-test sanity -v --docker default --test <test>	Runs a specific sanity test (e.g., pylint).
ansible-test units -v --docker default	Runs all unit tests.
ansible-test integration -v --docker <distro>	Runs integration tests on a specific distro container (e.g., ubuntu2204).
ansible-test ... --coverage	Runs specified tests with coverage reporting.

• Sanity/Unit Tests: Use the --docker default container.
• Integration Tests: Use a distribution-specific container like --docker ubuntu2204. Do not use default or base.

Sources: AGENTS.md:52-84, AGENTS.md:36-39

Documentation and Changelogs

Plugin Documentation

Modules and plugins require documentation to be included directly within the source file as static YAML string variables. These blocks are parsed via AST and cannot be dynamically generated.

• DOCUMENTATION: Contains the main documentation, including short_description, description, options, and author.
• EXAMPLES: Provides playbook examples as a multi-line string.
• RETURN: Documents the return values of the plugin.

Alternatively, documentation can be provided in a "sidecar" .yml file with the same name as the plugin.

Sources: lib/ansible/cli/doc.py:465-476, lib/ansible/modules/replace.py:15-22, test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py:643-677

Changelog Fragments

Every user-facing change requires a changelog fragment.

• Location: Create a new YAML file in changelogs/fragments/.
• Naming: Use {issue_number}-{short-description}.yml or {component}-{description}.yml.
• Content: The fragment must contain a valid section key (e.g., bugfixes, minor_changes) and a list of entries. Each entry describes the change.

Example changelogs/fragments/1234-fix-thing.yml:

bugfixes:
  - my_module - Fixed an issue where the thing would not frobnicate correctly. (https://github.com/ansible/ansible/issues/1234)

Valid sections are defined in changelogs/config.yaml.

Sources: AGENTS.md:131-132, AGENTS.md:211-218, AGENTS.md:145-146

Submitting Contributions

Pull Request Requirements

Before submitting a Pull Request (PR), ensure it meets the following criteria:

Component	Requirement
Changelog	A changelog fragment must exist in changelogs/fragments/ with a valid section.
Tests	Appropriate tests must be included. Unit tests should be functional, and integration tests are required for most plugin changes to validate the public API.
Branch	The PR must target the devel branch.
Backwards-comp.	Changes must not break backwards compatibility. A deprecation cycle of 4 releases is required for breaking changes.

Sources: AGENTS.md:129-136, README.md:76-77, AGENTS.md:228-231

Pull Request Review Process

The following diagram illustrates the typical PR review workflow, involving the contributor, automated CI checks, and human reviewers.

Issue Reporting

• Use Templates: Fill out the issue templates provided in .github/ISSUE_TEMPLATE/.
• Correct Repository: Ensure your issue is filed against the correct project (e.g., ansible-core, ansible-lint, a specific collection). If an issue is filed in the wrong repository, it will be closed with a note directing you to the correct location.
• Security Issues: Report security vulnerabilities privately to security@ansible.com. Do not file them as public GitHub issues.

Sources: hacking/ticket_stubs/bug_wrong_repo.md, AGENTS.md:202-208, AGENTS.md:224-226