How to contribute

ansible-core takes contributions through pull requests against the devel branch. The expectations are stricter than for many community projects: every change needs a changelog fragment, every behavior change needs a test, and CI must pass before review can finish. This page is the high-level checklist; the sub-pages drill into specifics.

The PR lifecycle

1. Open a discussion or issue first for non-trivial changes. The maintainers prefer to surface design questions before code lands.
2. Fork, branch from devel, and set up a dev environment per Getting started. All PRs target devel. Backports to stable-2.X happen after merge.
3. Make the change. See Patterns and conventions for the coding rules — the line limit is 160, type hints use from __future__ import annotations, and module imports must come after DOCUMENTATION/EXAMPLES/RETURN.
4. Add a changelog fragment under changelogs/fragments/. Format is described in Development workflow.
5. Add tests.
   • Unit tests under test/units/, mirroring the lib/ansible/ path of what you changed.
   • Integration tests under test/integration/targets/<feature_or_module>/ where applicable.
   • See Testing.
6. Run sanity, units, and the relevant integration target locally.
7. Open the PR. Use the templates under .github/PULL_REQUEST_TEMPLATE/. Set the issue type appropriately (bugfix, feature, etc.).
8. Watch CI. Azure Pipelines (.azure-pipelines/azure-pipelines.yml) runs sanity, units, integration on multiple containers, and Windows tests. The ansibot GitHub bot also leaves comments tagging owners and surfacing CI failures.
9. Address feedback. Maintainers will leave review comments. The bot will re-run CI on each push.

Required components for a PR

The maintainers consistently call out three things:

• Changelog fragment. Without it, the bot will block. See Development workflow.
• Tests that exercise the changed code. Random coverage doesn't count; the test should fail on devel and pass on your branch.
• Pre-existing CI green. Re-run ansible-test sanity locally before pushing.

Licensing constraints

Per AGENTS.md, all new code must be license-compatible:

• Code under lib/ansible/ (excluding module_utils/) must be GPLv3-or-later.
• Code under lib/ansible/module_utils/ defaults to BSD-2-Clause so it can be reused in modules outside ansible-core.
• New runtime dependencies must be license-compatible with both. When in doubt, raise the question on the PR.

What lands here vs. in a collection

A frequent maintainer response to new-plugin or new-module PRs is: this belongs in a collection. ansible-core rarely accepts new plugins; the engine and the small built-in module set are stable surface, and most new content lives in:

• community.general, community.network, community.crypto — the community catch-alls.
• ansible.posix, ansible.windows, ansible.utils — official Ansible-namespaced collections.
• Vendor-specific collections (e.g., cisco.ios, cloud.aws).

Bug fixes and improvements to existing behavior do land in ansible-core; new features generally don't.

Backwards compatibility

The project documents in AGENTS.md:

Backwards compatibility is prioritized over most other concerns. Deprecation cycle: 4 releases (deprecation + 2 releases + removal).

That means a behavior you deprecate in 2.19 must keep working until 2.22. Use Display.deprecated (lib/ansible/utils/display.py) or AnsibleModule.deprecate (lib/ansible/module_utils/basic.py) with version= set to the current version + 3.

Sub-pages

• Development workflow — branch, code, fragment, PR.
• Testing — ansible-test flavors, common patterns, when to use Docker vs. venv.
• Debugging — verbose output, breakpoints, the debug strategy plugin, AnsiBallZ leftover archives.
• Patterns and conventions — the rules in AGENTS.md plus a tour of the in-tree idioms.
• Tooling — ansible-test, sanity tests, CI configuration, log fetcher.