Get involved in Open Source today - How to contribute a patch to a GitHub hosted...

How to contribute a patch to a GitHub hosted Open Source project like Code 52

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.

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.

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://[email protected]/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.

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

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://[email protected]/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.

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

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.

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

• Screencast: Contributing to Open Source Projects On GitHub For .NET Developers Part 1