Development workflow

A practical guide to the day-to-day cycle: branch, change, test, fragment, PR.

Branch from devel

All PRs target devel. Stable backports happen after merge.

git fetch origin
git checkout -b my-fix origin/devel

The stable-2.X branches exist for currently-supported maintenance releases. Bug fixes get backported by maintainers (or by the contributor on request); critical fixes are also backported to the previous stable line.

Set up a dev shell

source hacking/env-setup

This puts bin/ on $PATH, sets PYTHONPATH=lib/, and exports a few ANSIBLE_* env vars. After sourcing it, ansible --version runs from your checkout.

Make the change

Match the surrounding code style. The repo-wide rules (from AGENTS.md and pyproject.toml):

• Line length 160, not 80.
• from __future__ import annotations at the top of every Python file.
• Don't add obvious comments.
• Don't document module parameters in docstrings — migrate to type hints if you encounter them.
• No trailing whitespace. Sanity will fail on it.

In lib/ansible/modules/, imports must come after DOCUMENTATION, EXAMPLES, and RETURN — these are static YAML strings that get parsed by AST without actually importing the module.

Add a changelog fragment

Every behavior-changing PR needs a YAML fragment in changelogs/fragments/. Naming convention:

• {issue_number}-{short-description}.yml if there's a tracking issue, e.g., 83721-fix-template-recursion.yml.
• {component}-{short-description}.yml otherwise, e.g., apt-handle-cache-locked.yml.

Never reuse an existing fragment — every PR gets its own file to avoid merge conflicts.

The valid sections (bugfixes, minor_changes, breaking_changes, deprecated_features, removed_features, etc.) come from changelogs/config.yaml. Format is:

bugfixes:
  - apt - handle cache lock contention by retrying with backoff (https://github.com/ansible/ansible/issues/12345)

The leading <component> - prefix is conventional and makes the per-section combined changelog readable. The trailing URL is optional but appreciated.

Tests

See Testing for the full breakdown. Quick summary:

• Sanity tests live in test/sanity/ and are driven by ansible-test sanity.
• Unit tests live in test/units/, mirroring lib/ansible/.
• Integration tests live in test/integration/targets/<name>/ — a directory of playbooks per feature or module.

The bot won't approve a behavior change without a test that exercises the new code.

Local verification

Before pushing:

# Sanity tests for everything you touched
ansible-test sanity -v --docker default <changed/file/paths>

# Unit tests for the area you changed
ansible-test units -v --docker default test/units/<area>/

# Integration tests if relevant (use a real distro container)
ansible-test integration -v --docker ubuntu2404 <target_name>

If Docker/Podman isn't available, --venv is a fallback for sanity but is unreliable for units and integration.

Open the PR

Use the templates in .github/PULL_REQUEST_TEMPLATE/PULL_REQUEST_TEMPLATE.md. The fields the maintainers care about:

• Issue type — bugfix, feature pull request, docs pull request, etc. (Adjust the template; ansibot keys off it.)
• Component name — root-relative path like lib/ansible/modules/apt.py. The bot uses this to assign reviewers.
• Summary — what you changed and why. Linking to the changelog fragment helps reviewers.

CI

Every PR triggers Azure Pipelines, configured by .azure-pipelines/azure-pipelines.yml. Pipelines run:

• Sanity (split into multiple jobs for parallelism).
• Units across the supported Python versions.
• Integration tests across many distro containers.
• Windows tests for the winrm/psrp paths.

The ansibot GitHub bot leaves comments summarizing CI failures with file:line references. Use gh pr checks <pr> to get direct Azure DevOps URLs for each job, and hacking/azp/download.py <build_id> to pull console logs locally for grepping. See Tooling for the log-fetch flow.

After merge

• Tag the PR for backport (backport/2.18, etc.) if it's a bug fix.
• Update related downstream collections if your change affects their tests.
• The release manager picks up changelog fragments at release time and assembles changelogs/CHANGELOG-vX.Y.rst.

Cross-links

• Patterns and conventions for code style and idioms.
• Testing for the test taxonomy.
• Debugging for what to do when something doesn't work.
• Tooling for CI, sanity-test internals, and the Azure log fetcher.