Are you interested in making your first ever contribution to an open-source project or a first contribution specifically to Ansible? You can do both at once!
If that sounds exciting, read this post.
Starting your open-source journey can feel overwhelming at first.
While we have some good beginner-friendly guides (linked at the end of this post), I hope walking you through a real example here will make your onboarding as an Ansible contributor even smoother.
During writing this post, it turned out that our example contribution would be a documentation update: doc fixes can be much easier to submit because you can use a shortcut - edit files right on GitHub by clicking the Edit button in its web interface.
However, while documentation contributions are highly valuable, we are also interested in contributing to code. This typically involves working locally, so for this post, I’ll take the slightly longer route and guide you through that process.
If you don’t have a GitHub account yet, please create one.
The following steps were done on Fedora 39.
1. What to start with?
Let’s assume we’re new and we have no specific idea how we want to contribute. We’ll go to the how can I help page.
We want to start with something easy. There are two links referring to issues labeled as easy to fix. We’ll click the Ansible collections one.
Alternatively, you can go to specific repositories of the collections/tools you use and search issues using the easyfix and good_first_issue labels there.
2. Find an issue to fix.
We’ve found one easyfix issue:
Let’s take it. Put a comment in the issue that you’re working on it.
3. Fork the repo.
Go to the target repo, which is in our case ansible-collections/community.rabbitmq, and fork it:
4. Install packages.
$ sudo dnf install podman git
5. Install ansible-core.
We need the ansible-test tool from ansible-core to run sanity tests later.
$ pip install ansible-core
6. Create the following directories in your home directory:
$ mkdir -p ~/ansible_collections/community
7. Clone your fork, change the location, add an upstream remote, and checkout a branch for our changes.
In my case:
$ git clone https://github.com/Andersson007/community.rabbitmq.git ~/ansible_collections/community/rabbitmq
$ cd ~/ansible_collections/community/rabbitmq
$ git remote add upstream https://github.com/ansible-collections/community.rabbitmq
$ git checkout -b fix_doc
Note that we cloned our fork (from our profile) and added the original repo as upstream.
8. Change the code.
$ vim plugins/modules/rabbitmq_user.py
As the issue wants us to improve the examples, we took a look at the EXAMPLES sections of the modules and found the following:
Using |- feels like overkill here as the task description is already very short. Let’s make it and other similar examples in the block a little bit more minimalist like this:
9. Run sanity tests against the changed file.
$ ansible-test sanity plugins/modules/rabbitmq_user.py --docker
If there are errors, fix them and run again. Do it until the tests pass. If there are errors unrelated to your changes, proceed with the next step.
10. Commit the changes and push the branch to the origin repo.
$ ansible-test sanity plugins/modules/rabbitmq_user.py --docker
$ git commit -a -m "rabbitmq_user: improve examples"
$ git push origin fix_doc
11. Go to the upstream repo and open a PR.
Go to the upstream repo, which is in our case ansible-collections/community.rabbitmq, and open a pull request.
If this didn’t appear automatically, click the New pull request button and choose appropriate branches.
12. As soon as CI gets green, put “ready for review” in the comments.
If some CI items got red, you clicked Details and you’re sure the errors don’t relate to your changes, ignore them.
13. After merge, update your local and remote main branch
After it gets merged, switch to the main branch locally and update it so that next time, when we create a branch from main for another contribution, it’ll be up-to-date. Push the changes to the origin repo as well.
$ git checkout main
$ git pull upstream main
From https://github.com/ansible-collections/community.rabbitmq
* branch main -> FETCH_HEAD
d070548..3ded25f main -> upstream/main
Updating d070548..3ded25f
Fast-forward
plugins/modules/rabbitmq_user.py | 6 ++----
1 file changed, 2 insertions(+), 4 deletions(-)
$ git push origin main
There we go, the main branch contains our first contribution!
Thanks for reading:) Any feedback is welcome in comments.
Useful references:
- How can I help? page: more ideas on how to contribute.
- Creating your first collection pull request: more generalized version of this post.
- Review checklist for collection PRs: review your changes before submitting a pull request, review others’ pull requests in collections.
- How to create an Ansible collection with a simple module step-by-step post.
- Running ansible-core from a clone: a more flexible way to run ansible-core for developers while testing as it allows to test against a devel version.