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 firstname.lastname@example.org:api-platform/api-platform
I do recommend to use
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 email@example.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
fix/3543-patch-update-nested-object to the
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.