Skip to main content
We’re excited to have you as a contributor to AWX! Have questions about this document or anything not covered here? Create a topic using the AWX tag on the Ansible Forum.

​
Things to Know Prior to Submitting Code

​
Code of Conduct

We ask all of our community members and contributors to adhere to the Ansible code of conduct. If you have questions, or need assistance, please reach out to our community team at [email protected].

​
Submission Requirements

All code submissions are done through pull requests against the devel branch.
  • Sign your commits: You must use git commit --signoff for any commit to be merged, and agree that usage of --signoff constitutes agreement with the terms of DCO 1.1.
  • No merge commits: Take care to make sure no merge commits are in the submission, and use git rebase vs git merge for this reason.
    • If collaborating with someone else on the same branch, consider using --force-with-lease instead of --force. This will prevent you from accidentally overwriting commits pushed by someone else.
  • Discuss large changes: If submitting a large code change, it’s a good idea to create a forum topic tagged with ‘awx’, and talk about what you would like to do or add first.

​
Fork and Clone the Repository

If you have not done so already, you’ll need to fork the AWX repo on GitHub. For more on how to do this, see Fork a Repo. 
git clone https://github.com/<your-username>/awx.git
cd awx
git remote add upstream https://github.com/ansible/awx.git

​
What Should I Work On?

​
Good First Issues

We have a “good first issue” label we put on some issues that might be a good starting point for new contributors.

​
Bug Fixes and Documentation

Fixing bugs and updating the documentation are always appreciated, so reviewing the backlog of issues is always a good place to start.

​
Feature Work

For feature work, take a look at the current Enhancements. If it has someone assigned to it then that person is the person responsible for working the enhancement. If you feel like you could contribute then reach out to that person.
Issue assignment will only be done for maintainers of the project. If you decide to work on an issue, please feel free to add a comment in the issue to let others know that you are working on it; but know that we will accept the first pull request from whomever is able to fix an issue.
If you work in a part of the codebase that is going through active development, your changes may be rejected, or you may be asked to rebase. A good idea before starting work is to have a discussion with us in the Ansible Forum.

​
UI Development

If you’re planning to develop features or fixes for the UI, please review the UI Developer doc.

​
Translations

At this time we do not accept PRs for adding additional language translations as we have an automated process for generating our translations. This is because translations require constant care as new strings are added and changed in the code base. If you find an issue with an existing translation, please see the Reporting Issues section to open an issue and our translation team will work with you on a resolution.

​
Pre-commit Hooks

When you attempt to perform a git commit there will be a pre-commit hook that gets run before the commit is allowed to your local repository. For example, python’s black will be run to test the formatting of any python files.
While you can use environment variables to skip the pre-commit hooks, GitHub will run similar tests and prevent merging of PRs if the tests do not pass.

​
Custom Pre-commit Hooks

If you would like to add additional commit hooks for your own usage you can create a directory in the root of the repository called pre-commit-user. Any executable file in that directory will be executed as part of the pre-commit hooks. For your convenience in user scripts, a variable called CHANGED_FILES will be set with any changed files present in the commit.

​
Submitting Pull Requests

Fixes and Features for AWX will go through the Github pull request process. Submit your pull request (PR) against the devel branch.

​
Increasing Acceptance Likelihood

Here are a few things you can do to help the visibility of your change, and increase the likelihood that it will be accepted:
  • Clean linter checks: No issues when running linters/code checkers 
    # Python formatting with black
(container)/awx_devel$ make black
  • Passing tests: No issues from unit tests 
    # Run pytest
(container)/awx_devel$ make test
  • Write tests: Write tests for new functionality, update/add tests for bug fixes
  • Small changes: Make the smallest change possible
  • Good commit messages: Write good commit messages. See How to write a Git commit message
It’s generally a good idea to discuss features with us first by engaging on the Ansible Forum.

​
Pull Request Guidelines

We like to keep our commit history clean, and will require resubmission of pull requests that contain merge commits. Use git pull --rebase, rather than git pull, and git rebase, rather than git merge. Sometimes it might take us a while to fully review your PR. We try to keep the devel branch in good working order, and so we review requests carefully. Please be patient.

​
CI Checks

When your PR is initially submitted the checks will not be run until a maintainer allows them to be. Once a maintainer has done a quick review of your work the PR will have the linter and unit tests run against them via GitHub Actions, and the status reported in the PR.

​
Reporting Issues

We welcome your feedback, and encourage you to file an issue when you run into a problem. But before opening a new issue, we ask that you please view our Issues guide.

​
Getting Help

If you require additional assistance, please submit your question to the Ansible Forum. For extra information on debugging tools, see the debugging documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us