Damir's Corner.

How to Submit a Patch to an Open Source Project on GitHub

Lately I am working a lot with SQLite and its .NET client sqlite-net. After discovering a bug and also fixing it in the local files included in the project I am working on I decided to also submit a patch for it. What better reason to finally try out the recently released GitHub for Windows do I need?

A couple of months ago I already submitted a couple of patches to other projects but just enough time has passed since then that in conjunction with a new tool I had to almost relearn everything from start. The rest of this post is a concise step by step guide to avoid this situation in the future.

Before I start, though, credit where credit is due: most of the information below can be found in the great blog post by Scott Hanselman and its comments. Whatever is missing, is probably taken from the GitHub help pages.

First we need to set up the environment and get the source from the repository:

• Install GitHub for Windows – definitely the best Git client available for Windows. Not only it provides a rich user interface for the most common tasks but it also sets up Git shell completely hassle free, including the keys for communication with GitHub. It can't get any simpler and I have yet to find a reason to choose a different client.
• Create an account on GitHub if you don't have it yet: either on the website or through GitHub on Windows.
• Navigate to the project you want to submit the patch for and fork it by clicking the Fork button in the top right corner of the page. This will create your own copy of the repository on the server to which you can commit your changes since you don't have write permissions for the main fork.

• To get the sources on your computer you need to create a local clone of the repository. Once again you only need to click the Clone in Windows button in the top left of the page. This will open GitHub for Windows and instruct it to immediately create the local clone. Be sure, though, that you are doing it on your own fork of the project. After forking you should be redirected to it but you can always easily recognize it because it's prefixed with your GitHub username.

Now you're ready to start changing the code. Just navigate to the repository in GitHub for Windows and click on the open in explorer item in the tools menu. You could also navigate directly to the GitHub folder inside your Document library where your local repositories are stored by default.

Once you've fixed the code and you're ready to commit the changes it's time to return to GitHub for Windows. On the left side of the window it will automatically show you all the changed files with the diffs just a click away. On the right side a dialog for entering the commit message will already be waiting for you. By the Git convention the commit message shouldn't be over 40 characters long – of course the optional extended description can be as long as you need it to be.

As soon as you commit the changes the sync button left to the previously displayed dialog gets enabled. Click on it and the changes will be pushed to your fork on the GitHub server.

As long as all the changes you have committed to your fork should be included in the patch, you're ready to go: click the Pull Request button in the top left of the GitHub webpage for your fork of the project, enter additional comments as to why you are submitting the patch and confirm the operation by clicking on Send pull request button.

Most of the time your fork probably won't contain only commits for the patch. In this case there's another step involved: setting up a branch with the right set of commits for the patch. To get this done you'll need to use shell.

• Open the shell by clicking on the open a shell item in the tools menu of your repository in GitHub for Windows.

• Add another remote repository, by convention named upstream, pointing to the original project. The right URL is listed on the project GitHub web page right of the Clone in Windows button:

  git remote add upstream https://github.com/praeclarum/sqlite-net.git
  

• Create a feature branch based on master branch of the new upstream remote. This is where you'll add your selected commits to.

  git checkout -b AsyncTransaction upstream/master
  

• The new branch is automatically selected as your current branch. It's time to cherry pick the commits you need. You'll need the SHA1 hash of each one which is conveniently listed at the top of the left side of GitHub for Windows when you have the right commit selected. Just move your mouse over it and click on it to copy it to clipboard. Repeat this step for all the commits that compose your patch.

  git cherry-pick 6eb9f3c4496b43d14592df4eb9539ac39cbd102f
  

• Once you're done push this branch to the GitHub server.

  git push origin AsyncTransaction
  

• Now you're ready to send the pull request for the merge. Just make sure you have the right branch selected (below the Clone in Windows button) on the web page of your fork of the project before clicking the Pull Request button. To be really sure you can always check which commits are included in the request before finally submitting it.

One last thing you'll often need to do is merge back the changes from upstream (original project repository) to your own fork: either after your pull request is accepted or even before that if enough new changes will get committed to the project while you're still working on the patch. Once again you'll need to use shell (make sure your current branch is master):

• First bring the changes from upstream to your local repository:

  git fetch upstream
  

• Next merge these changes to your master branch

  git merge upstream/master
  

• Now push these changes to origin (your project repository on server). The easiest way to do this is by clicking the sync button in GitHub for Windows.

This should be enough information to get you going. There's a lot more to learn about Git and GitHub, but there's plenty of resources available. I should know since I'm still learning myself.