Hosting your OSS project on github

Maybe you’ve heard me or others blather on about how great git is and how great github is to host git projects. Maybe you’ve heard it enough that you want to give it a shot or at least see what is involved in it and why us crazies think it’s so great. I’ll attempt to describe how one could go about moving their project to github and some tips for maintaining it. This is by no means a comprehensive guide, but it should be enough to get you started. Thankfully there is plenty of content on the net already so I’ll be doing a lot of linking.

Step 1 – Install Git and create your github account

Read through this awesome guide from Kyle Cordes.

Mac users – follow one of the guides on github to get git installed, then follow the rest of Kyle’s guide.

Step 2 – Import your svn project onto github

There are a few ways you can do this. Github makes it very easy by allowing you to just import an svn repository from their UI. Here’s a guide on github on some ways to do this.

Step 3 – Clone your project locally

Kyle’s guide talks about how to clone your repository. It’s pretty simple though, just type "git clone git@github.com:username/repositoryname.git". You can see your public (read-only) and private (read/write, use this one) clone url here on your project’s page, like this:

Step 4 – Setup your .gitignore

Unlike SVN’s abomination of ignoring procedure, git sticks to a single .gitignore file in the root of your repository to specify ignored files. This makes it very easy to get things up and ignored and keep them clean. In SVN, every time you add a project you’d need to ignore the bin and the obj directories for instance. In git, you just have one rule that always ignores them. Here’s a sample of my baseline .gitignore file:

obj
bin
_ReSharper.*
*.csproj.user
*.resharper.user
*.resharper
*.suo
*.cache
*~
*.swp
/Build
NDependOut

Once you’ve got that file set up, you’ll need to commit it and push it. There’s lots of guides on committing and staging and such and I’ll link to those below, but for now just do this:

git add .gitignore
git commit -m "Adding .gitignore"
git push

So what did that do? The first line, git add…, staged the added file for commit. All changes, adds, deletes, etc, must be "staged" before they are committed. Staging is a powerful thing, but I’ll let the other guides go into that. The next line, git commit…, committed your staged change to your local repository. This is so quick because it doesn’t actually talk to github. The change is only local. The next line, git push, actually pushes your changes up to the remote repository (github).

Step 5 – Learn

Time to pause for some learning. Like I mentioned, there’s a lot of great material out there already. Here are a few resources:

• An Illustrated Guide to Git on Windows – Great guide to using git on windows and all of the gui tools available with msysgit
• GitCasts – Some great screencasts showing how to work with git. A lot of content here, some are a bit long but they’re great learning tools.
• Why Git is Better than X – Great for showing people the difference between git and other source control solutions. Helpful sales tool if someone is on the fence.

Step 6 – Maintain and accept contributions

So now the fun part. You get git. You have your project on github. Now what? How do people send you patches? Do they still email you patch files? Isn’t there a better way? I thought I said git was better! Never fear, yes there’s a *much* better way to accept contributions now that you’re using git and on github. Remember, git is a distributed version control system. It was built for this stuff!

First, the benefits:

One of the coolest things you’ll notice after accepting your first patch from someone in git is that not only will you have all of their individual granular commits in your timeline (rather than one giant patch) but those commits will still be attributed to the original author and even maintain their original change date!

Next, how to contribute:

1. Find your repository on github.
2. Fork it (click the little fork button). Forking on github is not necessarily claiming that you’re going to go your own way with a project. I’ve seen people new to github get concerned when their project was forked, but really it’s just the beginning of the contribution cycle.
3. Clone your fork locally. For example,

   git clone git@github.com:aaronjensen/machine.git

4. Add a remote for the original repository, this way you can get any changes to that repository locally.

   git remote add machine git://github.com/machine/machine.git
   git fetch machine

5. Make local changes. Commit them. Push them.
6. Send a pull request. This will notify the original repository’s owner that you want them to pull your changes and merge them into their repository. Here’s a github guide on the subject.
7. Sit back and wait for the project owner to accept your patch!

Finally, how to accept patches:

As a project owner when one of these pull requests come in you’ll get a message in your inbox on github. From there, you can either manually pull from the command line like mentioned in the above github guide or, if there would be no merge conflicts, you can use github’s swanky Fork Queue UI to merge changes in from the site itself! Check out a post and a video about that.

Step 7 – Enjoy the pretty pictures

Github has some really cool graphs for all of the projects. I encourage you to check them out. here are a few from machine: