Scott Hanselman

Get involved in Open Source today - How to contribute a patch to a GitHub hosted Open Source project like Code 52

January 25, '12 Comments [21] Posted in Open Source
Sponsored By

It's been over 5  years since my post how to contribute a patch to an Open Source Project. That post is focused primarily on Subversion as the source control system. If you are using CodePlex and Subversion for example, those instructions work great. Here's the same idea for GitHub projects.

Folks email me all the time asking questions like "how can I be a better programmer?" "how do I get more experience?" or even the very specific "how can I make my resume more attractive?" My answer is almost always get involved in open source.

Work with an open source project. Fix a bug, do their website, write some documentation. You don't necessarily even have to write code. A lot of open source projects need help and that help can mean doing forums work, support calls, whatever. The thing that folks forget about open source is that it's most volunteers who are doing it for the love of it. They show up.

"80% of success is just showing up." - Woody Allen

Sometimes open source projects fail simply because only one or two people actually show up. Day after day. Using open source is easy, but making open source is hard.

NOTE: This example uses Git and GitHub. It is not meant to be comprehensive nor ideal. It is workable and works, but if you are considering working in Open Source or with Git for multiple projects and features you will want to explore more complete (and complex) workflows. There's an excellent "Git Workflow for Agile Teams" article, as well as a suggested Git Workflow from the NuGet team, and a fantastic screencast from Ryan Bates on contributing with Git as well as a fine screencasted introduction from Bobby Johnson.

Code 52

It can be an overwhelming thing, though, to jump into a large open source project that is already established. It can also be hard to decide which small project to start, because no one wants to waste their time. How do you choose?

Some lovely gents (Andrew Tobin, Brendan Forster and Paul Jenkins) over at Code 52 have started a great idea. A new coding project every week.

What a great idea! Nothing too hard that it can't be jumpstarted in a week. This totally lowers the barrier to entry and also encourages that things stay fresh. It also creates a bunch of great codebases for us (the community) to fork and spin off into larger projects that live longer than a week.

The guys says they figured a week because:

  • shorter timelines encourage achievable goals.
  • shorter timelines reduce the incentive to procrastinate.
  • more variety of projects to work on over a period of time.

Contributing a patch to a small Open Source project on GitHub

The Code52 projects are hosted on GitHub. I host some of my own projects on BitBucket and others on CodePlex. It doesn't really matter where a project is as long as it makes you happy.

Let's say I want to contribute a fix to the DownmarkerWPF project they worked on a few weeks back. There's a few things I can do.

Raise an issue

Filing a bug is literally the least you can do to help a project. Even better if it isn't a ragebug (where you just tell them how they suck) but includes everything you know about the issue, perhaps a stacktrace or a screenshot. Bonus points if you're kind in tone.

Suggest a Feature

Be helpful and suggest an interesting or innovative feature for their product. Bonus points if you include mockups, suggest a design or even better, start implementing it!

Fork the Code, change it, then do a "pull request"

With some SCC (Source Control Systems) you'll change the code locally package it up as a "patch/diff" file and send that file onto the project team for integration at a later time. You'll want to just use the website for spelling changes and easy stuff.

With some newer systems like Mercurial and Git you'll push your code to a central place and send a "pull request" that says "hey, the code is over here, pull it in, m'kay?"

GitHub will allow you to make changes in the browser, but that's not realistic for actual code changes. Let's get the DownmarkerWPF code, change it, and submit a pull request.

It's a lovely Markdown Editor for Windows. If you don't want the source and just want a decent zipped up version you can run, you can download it.

Markdown Editor for Windows

Since I am going to fix what I think is an "issue" I'll first make an issue on the site and claim it. It's issue 82, so I will remember that number.

My GitHub Issue

I'll fork the code from the website and then clone my copy to my local machine. Note the URL I'm using is my fork of the code.

C:\Code52>git clone https://shanselman@github.com/shanselman/DownmarkerWPF.
git
Cloning into DownmarkerWPF...
remote: Counting objects: 1870, done.
remote: Compressing objects: 100% (634/634), done.
remote: Total 1870 (delta 1347), reused 1728 (delta 1210)
Receiving objects: 100% (1870/1870), 11.40 MiB | 2.39 MiB/s, done.
Resolving deltas: 100% (1347/1347), done.

I could make a branch for myself to describe what I'm doing but I'm not going to because it's unnecessarily confusing for this example.

So, I love the idea of a Markdown editor for Windows as I'm writing a book with my wife using Markdown. However, my wife and I (and Leanpub.com) are using *.mkd as our extension, while the Code52 project uses *.md, *.markdown, and *.mdown. Here's an small but impactful change that I can make.

I'll find the code, and change it. Don't get overwhelmed now by the awesomeness and impact of this fix.

public static class Constants
{
public static readonly string[] DefaultExtensions = new[] { ".md", ".markdown", ".mdown", ".mkd"};
...
}

Now I'll compile and test the change. It works!

Behold the greatest bug fixed in the history of software

Now I'll commit my change locally, then push it to the server. Add, Commit, Push.

C:\Code52\DownmarkerWPF>git status
# On branch master
# Changes not staged for commit:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: src/MarkPad/Constants.cs
#
no changes added to commit (use "git add" and/or "git commit -a")

C:\Code52\DownmarkerWPF>git add .

C:\Code52\DownmarkerWPF>git commit -m "#82 - Added .mkd extension support"
[master 17c5704] #82 - Added .mkd extension support
1 files changed, 1 insertions(+), 1 deletions(-)

C:\Code52\DownmarkerWPF>git push
Password:
Counting objects: 9, done.
Delta compression using up to 12 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 453 bytes, done.
Total 5 (delta 4), reused 0 (delta 0)
To https://shanselman@github.com/shanselman/DownmarkerWPF.git
792d099..17c5704 master -> master

Cool, so now I can see on the website that my issue #82 has been associated with my change because I used the number in the commit message.

Look it's issues attached to commits!

Now I'll let the Project Administrators know where they can get it by pressing Pull Request on the website.

I'm issuing a pull request

Now I wait some number of minutes, hours or days for the owner of the project to accept my request. It's totally up to them what they accept and what acceptance criteria they have.

Here's my fix, now accepted, merged and closed by the Project Administrator. They will then close the issue.

My accepted pull request

Open Source isn't as scary as it seems. Go out there now and offer your help, time and assistance to your favorite project. Promote them, use them, fix their spelling and bugs. You can play with the Code 52 guys in their chat room on Jabbr or learn all about the project at the Code 52 website.

Related Links

About Scott

Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.

facebook twitter subscribe
About   Newsletter
Sponsored By
Hosting By
Dedicated Windows Server Hosting by ORCS Web
Wednesday, January 25, 2012 2:30:35 AM UTC
Bobby Johnson (@NotMyself) has a great set of screencasts explaining how to contribute to a OSS project on GitHub for .NET developers. Starts here: http://iamnotmyself.com/2010/09/05/contributing-to-open-source-projects-on-github-for-net-developers-part-1/

He shows how to install Git on Windows and set up public/private keys. Then how to set up a local repo and publish to GitHub. Finally how to fork and contribute to an existing GitHub project.
Wednesday, January 25, 2012 6:04:05 AM UTC
ScottK - Already added at the bottom of the post under "Related Links."
Wednesday, January 25, 2012 6:48:45 AM UTC
One thing that makes good sense when forking and doing pull requests on a regular basis, is to add an upstream branch that points to the upstream/master.

This requires the non-default upstream remote to be added:

cd Spoon-KnifeChanges
git remote add upstream git://github.com/octocat/Spoon-Knife.gitAssigns
git fetch upstream

Then, when you want to do a pull request you do a cherry-pick from the branch where you work is committed:

git checkout -b upstream upstream/master
git cherry-pick sha1
git push origin upstream

And on the website you have to switch to the upstream master.

This ensures that you only do a pull request for the commit that contains your patch.
Wednesday, January 25, 2012 6:59:41 AM UTC
mm :) Really nice idea! Will try to help and explore their code. Thank you for mentioning that code52 team.
Wednesday, January 25, 2012 8:03:47 AM UTC
Nice post Scott.

I discovered Code52 from one of your tweet.

The hardest part is: "How can I help them?"

Sometimes we can think a long time on how we can help an open source team.

I think we just need to get involved.
Wednesday, January 25, 2012 8:14:29 AM UTC
This is all very nice,

Most of the projects on Github are a nice lecture and they include tests, actually they try to encourage people to test their submitted code, witch is a great think.
Wednesday, January 25, 2012 9:32:18 AM UTC
I usually use great tutorial from NuGet team (start read from The Git Workflow)
https://github.com/NuGet/NuGetGallery/blob/master/README.markdown
andrex
Wednesday, January 25, 2012 9:40:39 AM UTC
Nice article, it just misses adding the unit test for the change :)
Wednesday, January 25, 2012 11:33:23 AM UTC
Great article. And this code52 team seems pretty cool. I'm into game development, so I have looked at their "Samurai" project, which I now "watch" on github.

Btw, that patch you pushed in this article - so mad programming skills - my eyes exploded.

:)
Wednesday, January 25, 2012 3:18:15 PM UTC
It might be worth doing a followup post on best practices... encouraging pull requests from master to master, or adding code without adding tests, is a bit of a faux pas on GitHub.
Wednesday, January 25, 2012 7:27:19 PM UTC
Nice article but I would recommend including the 'branch' part. I sent a pull request for a quick bug fix following the same workflow you describe to SquishIt, a great project by Justin Etheredge. Then I committed another change for an unrelated feature and it ended up getting automatically added to the first pull request [1]. Now the pull request is a mess and I don't know enough about Git/Github to fix it. :-(

I am not sure but I think using branches would have prevented this issue.

1. https://github.com/jetheredge/SquishIt/pull/102

PS. If anybody knows how to split these two out into separate pull requests please let me know!
Wednesday, January 25, 2012 7:35:11 PM UTC
Ya, honestly, I went back and forth on the branching thing. I actually including it, then talked to a few guys and removed it. It's hard. Honestly, Git and GitHub and their associated workflow have some significant subtleties that are non-trivial to the uninitiated. Showing the ideal workflow could be scary enough to scare someone off completely. Perhaps I can make an addendum to this post.
Wednesday, January 25, 2012 7:50:06 PM UTC
I found it easiest to learn/understand Git branches by using Git Extensions. Being able to actually see the graph, and manipulate it using context menus etc., was very helpful.

For a followup/addendum, one link you might like is A Git Workflow for Agile Teams, which is where I first saw the feature branching concept. It goes into rebasing too though, which is a bit advanced.
Wednesday, January 25, 2012 11:08:53 PM UTC
Ryan Bates did a great Railscast episode about this for his 300th a short while ago too: http://railscasts.com/episodes/300-contributing-to-open-source
Saturday, January 28, 2012 3:51:47 AM UTC
This is great, gave me the push I needed to get over cold feet. I submitted my first patch this week!

I'm confused about one thing...after submitting a pull request, and having the maintainer approve and merge it with the master branch, my forked repository (on the GitHub website) does not reflect the latest changes.

On my local machine, master is up to date, but how do I update master in the forked repo on github.com?

Great post, kudos.
Saturday, January 28, 2012 10:11:12 PM UTC
Superb post Scott, like others have said, this has given me the push that I have needed.

I would also like to take this opportunity to say a big thanks for the time and effort that I know you put into your podcasts. The latest one, "Phoney" featuring Jon Skeet is the latest in a long line of superb episodes.



Monday, January 30, 2012 6:05:21 PM UTC
Inspiring post. I KNOW I should contribute to open source but never do. I think part of this is that I'm afraid how other leet developers are going to view my code (still a bit self-conscious about that).

You give nice suggestions. Maybe I can go around fixing little things like spelling or writing documentation. Call me crazy but I do find some sort of satisfaction in writing documentation...as long as it doesn't turn into my full time job :)
Thursday, February 02, 2012 10:03:47 PM UTC
Very interesting article, thanks for sharing your views.
Sunday, February 05, 2012 8:06:30 AM UTC

I'm confused about one thing...after submitting a pull request, and having the maintainer approve and merge it with the master branch, my forked repository (on the GitHub website) does not reflect the latest changes.

On my local machine, master is up to date, but how do I update master in the forked repo on github.com?

You've probably figured this out by now, but I just figured it out and thought I'd post it for you or anyone else: http://help.github.com/fork-a-repo

Once you add the upstream (git remote add upstream) pointing to the original repo, then just do


// fetch changes from upstream, but don't merge into your master branch yet
git fetch upstream
// merge into master branch
get merge upstream/master
// push to forked repo on github
git push origin master
Saturday, January 26, 2013 3:07:33 AM UTC
Anybody knows what happened with this Code52 project?? All the activity seems to get stopped around March last year, no new projects seems them.. :S
Asier
Thursday, May 23, 2013 3:33:33 PM UTC
Awesome post. It helped me create my first issue and pull request. Looking forward to more contribution to open source projects :)
Comments are closed.

Disclaimer: The opinions expressed herein are my own personal opinions and do not represent my employer's view in any way.