Guide to Open Source contributions with github

# Git vs Github disambiguation

Git is a Version Control System (VCS) software created in 2005. It was initially build to handle the source code of the Linux Kernel and its contributions. The official website can be found at git-scm.com. There is also a comprehensive book that you can read online for free here.

Github is a company that hosts the Website Github.com. This website offers a user interface on top of the Version Control System Git. It has additional features like Pull Requests, a Bug Tracker (named Issues), project planning tools and even a Continuous Integration system.

# Contributing on Open Source software

Let’s say that you found a bug in some Open Source software. If you’re already there, you probably got the source of the code and began patching it. Using git, obtaining the source code of a Git repository is done using clone, for example:

git clone https://github.com/api-platform/api-platform
# or using ssh
git clone git@github.com:api-platform/api-platform

I do recommend to use ssh over https to avoid using credentials. Github has a good guide for connecting to github over ssh.

Now that you have the code, let’s go over the next steps to propose a patch. Before Git, the Linux team (and many other developpers) used to send over patches by email. With Git, we can work on a Fork graph, where every spike would be someone’s copy of the source code.

In github you can click on the “Fork” button next to the star to create a new repository on their service.

Inside the repository (cd api-platform) let’s start by setting up remotes. A remote is a tracked repository where we can follow changes. You can have many. I usually start by renaming the “original” one upstream and my fork origin. Indeed, we will “propose a patch upstream” once our version will be fixed.

git remote rename origin upstream

Then, let’s add our remote, in my case with Github it is:

git remote add origin git@github.com:soyuka/api-platform

When you have your patch ready, switch on a branch and commit:

git switch -c fix/3543-patch-update-nested-object
git add src/Api
git commit -m 'fix(api): update nested object' 

Now that we have our patch ready, we can push it. By default git tracks branches through the origin remote. Tracking help following changes on git branches.

git push
# is the same as
git push origin fix/3543-patch-update-nested-object

In the documentation of git push origin refers to the repository and fix/3543-patch-update-nested-object to the refspec.

Now if you want to do a Pull Request, you can navigate on the origin’s url on github and open a Pull Request. If you want you can still send the patch by email using:

git diff > 3543-patch-update-nested-object.patch

A patch can be added manually to a repository using git apply 3543-patch-update-nested-object.patch.

If you want to know more git tips I invite you to go through greg0ire’s presentation named Git Gud.