Getting Started Contributing to an Open Source Project

Perhaps some of you have shared a similar experience: You’re hanging out at a cocktail party having a great time and talking to other people about the creation time of lists versus tuples, and then the topic of conversation moves to what sort of open source projects everyone is working on. When it’s your turn to answer, you don’t have anything, and long, awkward silence ensues. So then, someone tries to move on to a less awkward subject in order to keep the conversation rolling and asks what everyone’s take on abortion is.

For me, I’d never contributed to an open source project before, but I’d consider myself a competent programmer and I’m fairly proficient with git. But the barrier of entry for me, at least in my mind, was actually getting started with my first pull request toward a project. I just submitted my first pull request to a project today, so I just wanted to document the step-by-step to metaphorically hold anyone else’s hand that hasn’t taken this small jump.

Find a Project to Contribute To

There’s a few different ways to find projects that can be contributed to. Github hosts a list of trending repositories that are always fashionable. You can also just use The Google and find popular repositories in your language of choice. For me, I’d heard Eric Mill on the Giant Robots Smashing Into Other Giant Robots Podcast (ep 110), and I found it to be a compelling show. Eric had made a call for any interested python developers to help contribute to The Inspectors General Repository.

Kind of a Tangent: Why This Project Interested Me

You can see the exact pitch for the importance of the project here, but the basic idea behind Inspectors General is that government websites have no standardization across the board, so aggregating government reports is nearly impossible, so the end result is that these reports are simply drowned out and ignored. I’m not really a fan of most government organizations, which I won’t get into, but inspectors general are supposed to be entities that keep government accountable.

As a former government employee myself in the Army, I’ve had experiences that were infuriating because of the Inspector General’s lack of power. To make a long story short, I had a commander that was blatantly taking illegal action, I took the problem to the IG, and they concurred that the actions were in fact conspicuously wrong. They then approached the commander about the issue, and what happened? Nothing. What could the IG do about it? Nothing. In short, as long as other government entities exist, I would like to see more power and authority given to the organizations created to keep other organizations accountable.

How to Contribute Walk-Through

Once a project is discovered and it resides on Github, the process can be relatively straightforward:

Fork the repository

On Github, you’ll need to fork the repository. “Forking” the repository basically means that you’re creating a copy of the primary repository where you’re free to sandbox and create whatever whacky branches you want. To do this, simply click the “fork” button from the project in GitHub.com. From there you can create “pull requests” from your forked repository to the upstream (primary) repository.

Clone the forked repository to your local hard drive

Navigate to a directory in your computer, preferably where other git projects reside, and clone your fork:

git clone https://github.com/{{ YOUR_GITHUB_USERNAME }}/inspectors-general

cd inspectors-general

Establish where ‘upstream’ is

“Upstream,” while it does not need to be called “upstream” is generally the term to denote the aforementioned primary repository, or where your repository was forked from. When the primary repo is updated with other peoples’ pull requests for instance, we can then easily copy the diffs into our own code with ease. To do this:

git remote add upstream https://github.com/unitedstates/inspectors-general

You can verify that you’ve done this step properly with a simple:

git fetch upstream

Setup an Environment

Instructions for setting up required dependencies can generally be found in the project’s README if it’s well documented. In the case of this project, Python3 was being used and a number of dependencies existed. Virtual Environments are therefore a great solution to setting up an environment per project. For me, I didn’t want to install Python3 system-wide or change the “site-packages” directory for the rest of the python programs on my system. So you can setup a virtual environment. Since Python3 was being used in this case:

virtualenv --python=python3.3 --no-site-packages ./.virtualenv

Now a .virtualenv directory exists in your repository. From here it’s a good idea to have git ignore the files in your virtual environment entirely. To do this open “.gitignore” with your editor of choice and add a single line for “.virtualenv”

Now, we can freely install additional python libraries without creating changes system-wide. In our case, a “requirements.txt” file exists which lists all of the required python packages in order to get the project working. We can install them into the virtual environment like so:

./.virtualenv/bin/pip install -r requirements.txt

Activate the Virtual Environment

Your virtual environment can be activated from the shell using:

source ./.virtualenv/bin/activate

Now, if you use python, the interpreter will be the one established by the virtualenv.

Find some work to do

Certain projects might have particular guidelines that they’d like all team members to abide by. It’s always a good idea to read the README. Issues can generally be found under the “issues” section of the project on Github, or in this case: https://github.com/unitedstates/inspectors-general/issues.

The team members within the repository are also likely to help get you started. The open source community is a collaborative environment to begin with, and in my experience people were more than helpful.

Do some work

This is the part where you do some stuff. Use your imagination.

Create a Pull Request

Once you’ve modified the files you need to change:

git branch {{ cool_new_feature_name }}
git checkout {{cool_new_feature_name }}
git add {{ filename }}
git commit -m "{{ really_awesome_title }}"
git push origin {{ cool_new_feature_name }}

Now navigate to https://github.com/{{ YOUR_GITHUB_USERNAME }}/inspectors-general, and there should be a button to create a pull request.

The End

At this point your pull request will be reviewed, it’s likely that you’ll get some feedback or some changes will need to be made, but assuming it’s production ready, an administrator will merge your code. And now, your next cocktail party will not be awkward!