Contribute to an open source project on GitHub

This document will guide you through the steps required to contribute some source code fix or enhancement to an open source project hosted on GitHub. It is a bottom-up tutorial, starting from signing up to GitHub.

As a real life example for this guide, we will make a contribution to a not-so-typical GitHub project, the Free Programming Books list. This project in GitHub is the source of content of the webpage List of Free Programming Books.

Sign Up to GitHub

First, you need to have an account on GitHub. There are non-free accounts for non-open-source projects, but for the purpose of this guide, and for contributing to Open Source software, you only need a free account.

Head over to github.com and Sign Up!

Fork a Project

In order to get the code of a project, edit it and send it back to the developers, you need to create a fork of the source code. For the purpose of this example, let's assume that your username is "ChuckNorris" (meh... as if Chuck Norris needs to fork and edit source code... the source code fixes itself to avoid being roundhouse kicked...).

Head over to the page where the project you are interested in is hosted. For our example, go to github.com/vhf/free-programming-books, and click on the Fork button. GitHub will take a few seconds, and will create a copy of the original repository under your account, in our example it would be github.com/ChuckNorris/free-programming-books.

Install Git

You will need git installed on your PC/workstation to download code from GitHub. On an Ubuntu (or other Debian-based) system, do:

sudo apt-get install git

On a CentOS or other RedHat-based system:

yum install git

All of the rest of these instructions in this guide are the same on Ubuntu (or similar) and CentOS (or similar) systems, although Ubuntu typically comes with newer version of packages, and might have better behaviour with Git operations. After you have installed Git, you should set your username and email address. These will be submitted with the changes that you will make, to the original repository:

git config --global user.name "Your Name"
git config --global user.email [email protected]

Download the source code

To download the source code locally on your PC/workstation, from your GitHub repository:

git clone https://github.com/ChuckNorris/free-programming-books.git

This will create a directory named after the project (in our example "free-programming-books"), and put the source code files inside. You can now browse the source code files locally, on your workstation.

Connect the local directory with the original GitHub repository

Now that you downloaded the source code from your own repository, git knows where to push the changes that you will make. In git parlance, your repository is the origin.

You will most probably need to also create a connection to the original GitHub repository, so that Git knows where to pull updates from. In other words, if the developers of the original project do some changes, you should be able to update your directory on your workstation with those updates, so that you always work on the most current version of the code. In Git parlance, the original repository is the upstream.

To add the upstream repository:

cd free-programming-books
git remote add upstream https://github.com/vhf/free-programming-books.git 

Now, every time you want to work on the project, you can get an updated version of it by running:

git fetch upstream

This will not change any files that you already edited locally, unless you also do:

git merge upstream/master

Edit source files and push changes

At this point, you should have a copy of the source code that you want to edit on your GitHub repository, the one that you forked from the upstream repository, and is now your origin. You should also have a local copy of the source code on a directory on your workstation.

You probably now want to edit one or more of the source code files, using the text editor of your preference. For the sake of this example, we will do a couple of changes in the file named free-programming-books.md, and then push them to the origin. The changes that we will do are:

  1. Add two programming books for the Picolisp language, and
  2. Add the Picolisp language to the table of contents.

For the record, here is the diff of the file before and after the changes:

[[email protected] free-programming-books]$ diff -u free-programming-books.md-original free-programming-books.md
--- free-programming-books.md-original  2014-01-29 13:10:05.502982051 +0200
+++ free-programming-books.md   2014-01-29 13:06:00.659982149 +0200
@@ -108,6 +108,7 @@
 * [PC-BSD](#pc-bsd)
 * [Perl](#perl)
 * [PHP](#php)
+* [PicoLisp](#picolisp)
 * [PostgreSQL](#postgresql)
 * [PowerShell](#powershell)
 * [Processing](#processing)
@@ -1250,6 +1251,11 @@
 * [PHP 5 Power Programming](http://www.informit.com/content/images/013147149X/downloads/013147149X_book.pdf)


+###PicoLisp
+* [PicoLisp by Example](http://www.scribd.com/doc/103733857/PicoLisp-by-Example)
+* [PicoLisp Works](http://www.scribd.com/doc/103732688/PicoLisp-Works)
+
+
 ###PostgreSQL
 * [Practical PostgreSQL](http://www.commandprompt.com/ppbook/)

You can get a result similar to the above with git diff.

After you edit the source code file that you want, and save it on your workstation, it's time to push the changed file to your own GitHub repository, the origin. First, you commit your change to Git. This only affects files locally on your workstation. In this example, the file name is free-programming-books.md:

git commit free-programming-books.md -m 'Added two books on PicoLisp'
git push origin master

The commit command "gave" the changed file to Git to handle, with a short comment given after the -m option, and then the push command asked Git to push the committed file to GitHub, to the master branch of the origin repository. You will be asked for your username and password to GitHub during the push.

You can visit your GitHub repository now, and you will be able to see that the file you edited and pushed has changed.

Ask the original developers to pull your changes

After you have edited one or more files, committed them to Git and pushed them to your own repository on GitHub, you will probably want to ask the developers of the original source code, the one that resides in the upstream to review your changes, and merge them into the project, if applicable.

This action is called a pull request, and is clearly documented at Using Pull Requests on github.com. For the record, and for the completion of the real-world example used in this guide, the result was Pull Request 672 on the Upstream repository.

Conclusion

The procedure outlined above might seem too much at first, but after a couple of times, you will realize that it's actually pretty simple. If you were to count the commands used here, you would only have a handful. So, go ahead, become an open source developer!