Contributing to GitHub projects

I often see people asking how to contribute to an open source project on GitHub. Some are new programmers, some may be new to open source, others aren’t programmers but want to make improvements to documentation or other parts of a project they use everyday.

Using GitHub means you’ll need to use Git, and that means using the command-line. This post gives a gentle introduction using the git command-line tool and a companion tool for GitHub called hub.

Workflow

The basic workflow for contributing to a project on GitHub is:

  1. Clone the project you want to work on
  2. Fork the project you want to work on
  3. Create a feature branch to do your own work in
  4. Commit your changes to your feature branch
  5. Push your feature branch to your fork on GitHub
  6. Send a pull request for your branch on your fork

Clone the project you want to work on

$ hub clone pydata/pandas

(Equivalent to git clone https://github.com/pydata/pandas.git)

This clones the project from the server onto your local machine. When working in git you make changes to your local copy of the repository. Git has a concept of remotes which are, well, remote copies of the repository. When you clone a new project, a remote called origin is automatically created that points to the repository you provide in the command line above. In this case, pydata/pandas on GitHub.

To upload your changes back to the main repository, you push to the remote. Between when you cloned and now changes may have been made to upstream remote repository. To get those changes, you pull from the remote.

At this point you will have a pandas directory on your machine. All of the remaining steps take place inside it, so change into it now:

$ cd pandas

Fork the project you want to work on

The easiest way to do this is with hub.

$ hub fork

This does a couple of things. It creates a fork of pandas in your GitHub account. It establishes a new remote in your local repository with the name of your github username. In my case I now have two remotes: origin, which points to the main upstream repository; and joeshaw, which points to my forked repository. We’ll be pushing to my fork.

Create a feature branch to do your own work in

This creates a place to do your work in that is separate from the main code.

$ git checkout -b doc-work

doc-work is what I’m choosing to name this branch. You can name it whatever you like. Hyphens are idiomatic.

Now make whatever changes you want for this project.

Commit your changes to your feature branch

If you are creating new files, you will need to explicitly add them to the to-be-commited list (also called the index, or staging area):

$ git add file1.md file2.md etc

If you are just editing existing files, you can add them all in one batch:

$ git add -u

Next you need to commit the changes.

$ git commit

This will bring up an editor where you type in your commit message. The convention is usually to type a short summary in the first line (50-60 characters max), then a blank line, then additional details if necessary.

Push your feature branch to your fork in GitHub

Ok, remember that your fork is a remote named after your github username. In my case, joeshaw.

$ git push joeshaw doc-work

This pushes to the joeshaw remote only the doc-work branch. Now your work is publicly visible to anyone on your fork.

Send a pull request for your branch on your fork

You can do this either on the web site or using the hub tool.

$ hub pull-request

This will open your editor again. If you only had one commit on your branch, the message for the pull request will be the same as the commit. This might be good enough, but you might want to elaborate on the purpose of the pull request. Like commits, the first line is a summary of the pull request and the other lines are the body of the PR.

In general you will be requesting a pull from your current branch (in this case doc-work) into the master branch of the origin remote.

If your pull request is accepted as-is, the maintainer will merge it into the official upstream sources. Congratulations! You’ve just made your first open source contribution on GitHub.

(This was adapted from a post I made to the Central Ohio Python User Group mailing list.)