Contributing to Open Source Software with Git

Learn what is open source software and how you can make your contributions to a open source project using Git.

In the past decade or so, open source software has come a long way. Initially, when it came to developing enterprise level applications, engineers and developers would simply opt for proprietary software for a multitude of reasons.

Such a frame of mind has shifted drastically and as things stand at present, there are a number of highly successful enterprise and commercial products built using open source software. A few cases in point would be Twitter(Rails), Github(Rails), Snappy(Laravel), Paypal(NodeJS) and countless others.

The beauty of open source software lies in the fact that there are millions of software developers, investing their spare time to improve a single software project without even charging a cent, though there are a lot of intangible benefits to take home from it, which we will look at later in a bit of detail.

During the course of this tutorial, you will learn.

  1. What is open source software.
  2. The benefits of contributing to an open source project.
  3. Setting up your environment before making your first contribution.
  4. A typical workflow to follow while making a contribution.

This tutorial assumes you have a basic knowledge of Git. It is more focused on how Git fits into the whole process.

Understanding Open Source Software

Let us first understand what is open source software and how it really works.

I will quote an excerpt from the official open source website.

Generally, Open Source software is software that can be freely accessed, used, changed, and shared (in modified or unmodified form) by anyone. Open source software is made by many people, and distributed under licenses that comply with the The Open Source Definition.

A better way to understand this would be to look at how the opposite of this works.

For the sake of argument, suppose I made a really cool blogging platform like Ghost. Since I intend to earn from it, I came up with an on-site hosting plan that my users can subscribe to host their blogs. I also throw in a few neat features like custom domains, and automatic backups.

Though I can build on this and provide as many features as I like, at the heart of it, I really do not intend to make my blogging platform's source code public. If I did that, anyone could set it up on their servers for free, and modify it anyway they like.

Also, since the blogging platform is my product and I have copyrighted it to myself, I have also entitled myself to a right to legal prosecution in case say, someone maliciously obtained the source code of my blogging tool.

Sounds too complicated? I am really just getting started but I will stop it there.

Open source software works the opposite way. Under that context, I would just make the source code of my blogging platform publicly available to be used by anyone and be modified in any way.

As simple as this sounds, there is still the licensing part involved.

There are a number of licenses that you can apply to your open source projects. The most widely used is the MIT license and you can read about it if you are interested in the details.

Benefits of Contributing to Open Source Software

If you are one of those who will need a little convincing before you start contributing to open source software, let us dive into the advantages right away.

Sense of Giving Back to the Community

Software development is a collaborative process. I can hardly imagine the software industry to be where it is today if every software developer/team worked in isolation.

You use a good number of code pieces(in the form of plugins. modules, functions) written by other developers, not to mention the countless Stackoverflow threads that are just sitting there to help you out if you ever get stuck.

A software developer does consume a lot of code written by other fellow developers during his professional lifecycle and it feels really good to contribute and give back to the community that helps you in so many ways.

Strengthening your Portfolio

Open source projects can add a great deal of substance to your Curriculum Vitae. Imagine if David Heinemeier Hansson walked into an interview and started his introduction by saying he is the creator of the Rails framework. What kind of impact would that have on the complexion of the interview?

Surely this is an exaggerated example but you get the point.

Growing as a Developer

It is impossible to make an open source contribution before reading and fully understanding the available code. Diving into code written by other developers can help you expand your technical horizon and open you up to nobel programming constructs and techniques. In general, it can also help you see the bigger picture and how to go about good software design.

Making Yourself Known

I think I can dub contributing to open source software as a free technical marketing campaign. Amidst all those reported issues and pull requests, one thing stands out and that is you, the person who is making all the effort.

Need I say more?

Setting up your Environment

Before you setup the tools of the trade, I must say Git has vastly simplified the process of contributing to open source software. Yes, the open source community functioned perfectly before Git but the workflow just did not come so naturally as compared to the post-git era.

The role of Github cannot be under estimated either. It took something as beaufitul as Git and further simplified the whole process.

Installing Git

Open up your terminal and execute the following command to install Git.

# on OSX
$ brew install git

# on ubuntu
$ sudo apt-get install git

The brew command users Homebrew which is a package manager for OSX.

If you are on Windows, you can download an executable installer.

For information about installing Git on different distributions of Linux, you can look at the official documentation.

Configuring Git

Once you have installed Git, you need to configure a few variables.

Git stores configuration in a numer of places and prioritizes it's use. If you are interested in the details, you can have a look at the official documentation.

Execute the following commands in your terminal, replacing the place holders <> with the appropriate information.

$ git config --global user.name "<your-username>"
# example: git config --global user.name "Noman ur Rehman"

$ git config --global user.email "<your-email>"
# example: git config --global user.email "me@example.com"

$ git config --global push.default "simple"
# sets the simple push strategy which pushes
# from local branch(of the same name) to
# the remote branch(of the same name)

$ git config --global core.editor "<path-to-your-editor>"
# example: git config --global core.editor "/Volumes/Media/Applications/Sublime\\ Text.app/Contents/SharedSupport/bin/subl"

If you are more into graphical user interface tools, you can look at the Github desktop client.

There are a lot of other Git configuration variables you can set but these should be enough for a start. Since Git is the only tool you need, let us now move to the contribution workflow.

Open Source Contribution Workflow

Selecting a Project

There are two parts to selecting a project, the which and what. Which project do you wish to contribute to and what do you wish to contribute to it.

The answer to the which part can be an open source project you have used a lot over the years or simply using Github to search for your desired project. You should also take into account the code complexity when choosing a project.

Based on your experience, you might find it hard to get your head around a certain project. Do not take it as a setback but rather as a stepping stone. In such a case, go for something that is right down your alley and will make the ride a lot smoother.

The answer to what can be a feature you think would be nice if added to the project you selected. You can also look into the reported issues for a project and work on resolving them. Some projects also have certain TODO comments. You can also see if you can work on these TODO items.

Reading the Contribution Guide

At times, the owner of the project writes a contribution guide in the wiki section or as part of the readme for the project.

Be sure to read it first. It is nice to follow the process outlined by them as it serves to ease up the process for both parties.

Making a Local Copy

Forking is the process of making your personal clone of the project and downloading it to your local machine.

Here is how to fork a project.

On the project's Github page, you will notice a Fork button at the top-right corner. Simply click this button and a copy will be created under your username.

The next step is to copy the git url of the project which can be found under the commits/branches/releases/contributors header.

Once you have done that, execute the following command in the terminal.

$ git clone "<the-copied-git-url>" "<directory-name>"
# example: git clone "https://github.com/nomanurrehman/stripe-ruby-mock" "stripe-ruby-mock"

You now have the code copied and ready to be edited in the directory you specified.

All projects have a base master branch that contains the fully tested, bug free, stable code.

You can check the branch you are currently working on by executing the following commands.

# move to the root of your project
$ cd <directory-name>
# example: cd stripe-ruby-mock

# show branch
$ git branch

Notice that the master branched is marked with a ***** which means you are currently on it.

At this point, you can execute the unit tests to make sure everything is working as expected. If any of the tests fail later, they can help you identify the problem areas.

Writing Code

It is obvious that before you write any line of code, you must understand the project's overall design and coding constructs. It seems silly to write it down as a separate step.

Sadly, this part is something no tutorial or magic potion can teach. It all depends on the level of expertise and experience you have overall.

As a rule of thumb though, majority of the projects have a single entry point. A code file at the root that calls in all the different parts to do it's work. You can slowly build your way up from there, understanding how each part and how all the parts in cohesion work.

Also be sure to make your commits to the development branch, merging later into the master branch when done. It is a neat practice to follow.

Building on from the last command you executed to check the branch, you can run these commands to switch to the development branch.

# switch to development branch
$ git checkout development

You can also create a development branch if the project does not have one.

# create development branch
$ git checkout -b development

Also make sure that your commits are atomic that is each commit should introduce a small change as that helps to chop and change things later if required.

For example, instead of committing a whole class, make the first commit as an empty class. In the second commit, add the contructor for the class. Similarly, in a series of steps, add the class methods.

Writing Unit Tests

Once you are done with writing code, writing unit tests is equally important.

Beware, this part can be easily over-looked and you may be a little lazy in your test coverage but be as comprehensive as you can be. Make sure to test the new code in every way possible.

Writing unit tests is helpful because other contributors can make sure(before writing their own code) everything is working correctly by simply executing the test suite.

Based on your project's base language, the unit test framework may vary. Ruby projects mostly use RSpec whereas PHP has the PHPUnit package.

Sending a Pull Request

Assuming you have written the code and the unit tests and committed all of them neatly to your development branch, you can merge the development branch into the master branch.

# switches to master branch
$ git checkout master

# merges development into master
$ git merge development

To send a pull request, you can use Github or the command line.

For the Github part, here is how to do it.

On the project's Github page, and click the New pull request button.

The next page should give you an option to compare branches. Click the compare across forks. link on this page.

You should now have the option to select the base fork and branch alongwith the head fork and branch.

The base fork is the repository you forked from whereas the head fork is your forked repository. Also make sure to compare the same branches from both the repositories.

Once you have selected the base and head fork, simply click the Create pull request button.

The owner of the project will be notified of the pull request and you can wait on them for the merge or feedback comments.

Incorporating Pull Request Feedback

At times, the owner might have feedback on the contribution you made. Maybe you missed a certain scenario in the unit tests or a function could have been written a better way.

You can read the comments on your pull request and repeat steps 4 and 5 until your contribution is accepted.

It could also be that while you were busy writing your code, someone else's contribution was accepted and the master branch(of the main repository) moved ahead.

In such a scenario, you will need to add the git url(as another remote) of the project(you forked from) to your local git repository and merge the respective master branches. You can find the git url of the source project just like you found the git url of the forked project in step 3.

Execute the following command to add the remote of the forked repository.

# adds remote of forked repository
$ git remote add "<remote-name>" "<git-url>"
# example: git remote add "rebelidealist" "https://github.com/rebelidealist/stripe-ruby-mock.git" 

# pulls master from added remote
$ git pull <remote-name> master
# example: git pull rebelidealist master

Your local master branch is now updated.

Pull Request Acceptance and Merging

There is not much you can do for this part other than be happy and feel useful.

When your pull request is accepted, it will be marked as Merged.

Perhaps tweet about it and let your followers know about your contributions?

Final Thoughts

Open source software is all about the sense of community. It is a great feeling to know your contribution will be impacting hundreds of projects, just like contributions from fellow developers have impacted your personal and professional projects.

If you have an idea, provided it's somethis useful, and such an open source project is not out there, start your own. If given the right exposure, you will be surprised to see how many people are willing to contribute.

I hope you found this tutorial interesting and knowledgeable. Until my next piece, happy coding!

Noman Ur Rehman

I am a full stack, freelance web developer who specializes in Laravel, Rails, and Amazon Web Services. I love Regular Expressions and discussing ideas.