NETWAYS Blog

Today I want to share my workflow for contributing to projects hosted on GitHub because I believe it works very well for me and I regularly contribute to various projects. Of course most of this also applies to other hosted Git platforms like GitLab. It will not involve any Git magic as there are other posts to do that. So let’s use adding a check command to Icinga 2 as my example.
The obvious first step is finding the Git repository for the project and reading contribution guidelines because there are some projects which aren’t hosted on GitHub and some have additional requirements like submitting an issue in addition to a pull request. You should always familiarize yourself with and stick to those policies if you want your pull request to be accepted. For Icinga 2 there currently aren’t any additional project-specific guidelines.
Your next step is to create a fork on GitHub and clone the repository. So in the GitHub web interface click on „Fork“ and select your own account (or company account as long as you are allowed to push). Once you’ve forked the repository you can check out a local copy using the following command:

git clone git@github.com/dgoetz/icinga2.git

Afterwards you should add another „remote“ for the original Git repository in order to be able to update your own repository with changes from the upstream project:

cd icinga2/
git remote add upstream git@github.com:icinga/icinga2.git

After these initial steps you can create a Git branch for your feature or bug fix. Using the „master“ branch for pull requests is strongly discouraged because things tend to get complicated once you have more than one pull request. Another recommendation is to use branch names that match the upstream repository’s style. This however is not a hard requirement:

git checkout -b feature/expand-check-foo

This also automatically switches to the newly-created branch which means you can now start to edit files for your pull request. Once you’re done you can add them to the Git index and create a commit. Typically upstream projects have guidelines for this, so do not forget to include documentation, make only one commit out of your work (perhaps by squashing) and so on.

vi itl/plugins-contrib.d/network-components.conf
vi doc/10-icinga-template-library.md
git add itl/plugins-contrib.d/network-components.conf doc/10-icinga-template-library.md
git commit -m "ITL: expanded check foo"

Afterwards push your commit to your forked repository and then create your pull request using the GitHub webinterface:

git push -u origin feature/expand-check-foo

When creating the pull request make sure to provide a detailed description of your changes and the reason why you feel that your pull request should be merged. Keep the setting checked to allow edits from maintainers. Depending on the project make sure to reference any related issues, fill in their pull request template or do whatever else they require for pull requests.

Typically once a pull request is created automated tests will be run and a review process by the project team will start, so it’s possible that you’ll be asked to make changes before your pull request is accepted. If this happens simply edit your branch to fix whatever problems were found during the review, amend your commit and force push it to your fork. This will also automatically update your pull request but you might want to provide a comment for the pull request as to what has changed:

vi doc/10-icinga-template-library.md
git add doc/10-icinga-template-library.md
git commit --amend -m "ITL: expanded check foo"
git push -f

Another commonly requested change is that you rebase your branch before the pull request is accepted. This usually happens when significant changes were made to the upstream repository while your pull request was waiting to be merged. In order to rebase your branch the following commands should be all you need, however in some cases you may also have to manually resolve conflicts:

git pull --rebase upstream master
git push -f

And of course you will sometimes want to create additional pull requests. For these make sure to start with a new branch based on the upstream repository:

git checkout master
git pull upstream master
git checkout -b fix/check-bar
...
git push -u origin fix/check-bar

So, this is it, this is my basic workflow for easy contributions on GitHub. I hope it helps you to get involved with your favorite projects and your fixes and features to get upstream. If you prefer to do all step in the command line, you can have a look at GitHub’s command-line wrapper for git hub. If you need more general Git knowledge I recommend the Git book and our training. If you need a GitLab system to play around, have a look at our NWS platform.

Dirk Götz

Principal Consultant

---

Dirk ist Red Hat Spezialist und arbeitet bei NETWAYS im Bereich Consulting für Icinga, Puppet, Ansible, Foreman und andere Systems-Management-Lösungen. Früher war er bei einem Träger der gesetzlichen Rentenversicherung als Senior Administrator beschäftigt und auch für die Ausbildung der Azubis verantwortlich wie nun bei NETWAYS.

Lies mehr von Dirk und triff unser Team