Collaboration on GitHub: a Practical Intro

cover

Open-source software (OSS) is fascinating, right? People from different places all over the world can work on a certain code repository and improve it piece by piece to make great things happen. The Linux kernel (that powers servers, Android phones, and some desktop computers) is an open-source project. Most of what runs the web on frontends and backends are open-source libraries written in JavaScript, Python, and other languages.

This model of public and open collaboration has been successful for quite some time now, and everyone is invited to join and push OSS forward. So, this article will introduce you to the collaboration process on GitHub. It is assumed that you know the basics of Git and GitHub. In particular…

If you have the least amount of experience with these things, then the content you’re about to read here will be a great next step in your coding journey.

Why Collaborate?

Even if you’re already looking forward to contributing OSS and don’t need much convincing, it’s nice to know the benefits of what you’re getting into.

With the motivation out of the way, let’s get started!

The Big Picture

These are the general steps that we will discuss in some detail in the next section using an actual code repo I made for demonstration.

Demonstration

I have created a dummy repo to demonstrate the process on. The repo is created and owned by my account (waseem-medhat, the maintainer), but the changes and the pull request will be submitted by a separate account (wipdev-collaborator, the collaborator) to show the process from both perspectives.

So, the story is that the maintainer started a repo with a simple README.md, but it has some typos. The collaborator wants to correct these typos for the maintainer, and the whole process of doing that is shown below step-by-step.

Side note: in this article, we will show the minimal work you need to get started. If you want to learn more, GitHub has fully detailed documentation on that subject. You can check it out here.

Fork

When you want to make contributions to a repo on GitHub, you cannot do this right away because you are not authorized to push code directly to it. For this reason, you should fork that repo, which means you get a copy of it on your GitHub account, allowing you to make changes as you want.

So, the collaborator proceeds to fork the upstream repo as shown below. It’s as simple as clicking a couple of buttons. There is rarely a need to modify anything.

repo fork

fork dialog

After doing that, and waiting for a couple of seconds, the collaborator now has on their account a copy of the main branch of the maintainer’s repo as wipdev-collaborator/hello-world, shown in the screenshot below. Notice that it’s stated in the repo where it is forked from.

new fork

Clone, Update, Push

Updating forks works the same as updating original personal repos. So, after you fork a repo, you’re free to work with it using the same process you’re already familiar with when working solo.

So, the collaborator does the following:

After all the steps above, the fork’s page looks like this. When no further commits are needed to be made, that popup with the “Compare & pull request” button is where the next step happens.

new branch

Pull Request

Changes to your fork will remain local to your fork until you submit a pull request, which is a request for the maintainer to pull your new changes into the upstream (maintainer’s) repo.

So, the collaborator proceeds to the PR page, captured below. Notice that the base now is the main branch of waseem-medhat/hello-world which is the upstream repo. Now, the collaborator can take a final look at the diff at the end of the page, write a comment to the maintainer if necessary, and finally creates the PR.

If you were following along and submitted a PR in some repo, then I congratulate you for making your first contribution to OSS!

pull request

Merge

The collaborator’s job is done. Now, it’s up to the maintainer to see the changes and then merge the pull request or write a comment to the collaborator for further follow-up. After merging, the new changes are now added to the upstream repo.

pr merge

final repo

Final Notes

You see, the process is straightforward, and you can do it right away whenever you have something to add to a project. It could be as simple as correcting typos in Markdown files, or it could be a bug fix or a new feature. The point is, everyone at all skill levels can have something to contribute, and that’s what’s great about OSS.

One thing to watch out for, though, is that other people can be working on the same repo at the same time. You need to make sure your fork is in sync with the upstream, which can be done by updating the fork on GitHub or adding the upstream repo to the Git config on your local machine.

That’s it! I hope that was helpful, and good luck with your OSS endeavors!


Shout out to Nik F P for suggesting the idea of this article and reviewing it.

Cover image source: https://wallpapercave.com/github-wallpapers