Collaborating to projects on GitHub

Author

Marie-Hélène Burle

There are countless free and open source tools on GitHub and if you use one such tool and find a problem or think that you can improve the project, or if you would like to request a novel feature, how do you go about it?

In this workshop, we will learn how to contribute to open source projects hosted on GitHub by opening issues and submitting pull requests.

Before we start: setting up a GitHub account

If you don’t already have one, sign up for a free GitHub account.

To avoid having to type your password all the time, you should set up SSH for your account.

Opening issues

The easiest thing to do, if for instance, you are having problems with the tool, found a bug, or want to submit a feature request, is to open an issue.

GitHub has also now implemented the ability to open “Discussions”. If enabled by the maintainer of a project, this is the place where you want to ask for help.

Forking a project

Now, a more advanced approach is to actually make changes to the code of the project.

If you want to develop your own version of the project, you can fork the GitHub repository: go to GitHub and fork the project by clicking on the “Fork” button in the top right corner.

You have all privileges on the forked project. So you can make any change you want there. You can clone it to your machine and develop the fork. But your fork does not get updated to the improvements made to the initial project. It is an independent project of its own.

Keeping a fork up to date

If you want to keep your fork up to date with the initial project, you need to:

1. Clone your fork on your machine

This will automatically set your fork on GitHub as the remote called origin:

# If you have set SSH for your GitHub account
git clone git@github.com:<user>/<repo>.git <name>

# If you haven't set SSH
git clone https://github.com/<user>/<repo>.git <name>

2. Add the initial project as upstream

Add a second remote, this one pointing to the initial project. It is usual to call this remote upstream:

# If you have set SSH for your GitHub account
git remote add upstream git@github.com:<user>/<repo>.git

# If you haven't set SSH
git remote add upstream https://github.com/<user>/<repo>.git

3. Pull from upstream

You can now pull from upstream to keep your fork up to date.

From there on, you can pull from and push to origin (your fork) and you can pull from upstream (the initial repo).

Of course, if your project and the initial one diverge in places, this will lead to conflicts that you will have to resolve as you merge the pulls from upstream.

Most of the time however, you don’t want to develop your own version of the project. Instead, you want to make the initial project better by contributing to it. But you can’t push changes to upstream directly since you are not part of that project. You don’t have write access to that repository. If anybody could push to any project, that would be utter chaos.

So how do you contribute code to someone else’s project?

Creating pull requests

Here is the workflow as described in the Git manual:

  1. Pull from upstream to make sure that your contributions are made on an up-to-date version of the project
  2. Create and checkout a new branch
  3. Make and commit your changes on that branch
  4. Push that branch to your fork (i.e. origin—remember that you do not have write access on upstream)
  5. Go to the original project GitHub’s page and open a pull request from your fork. Note that after you have pushed your branch to origin, GitHub will automatically offer you to do so.

The maintainer of the initial project may accept or decline the PR. They may also make comments and ask you to make changes. If so, make new changes and push additional commits to that branch until they are happy with the change.

Once the PR is merged by the maintainer, you can delete the branch on your fork and pull from upstream to update your local fork with the recently accepted changes.