Bob's Blog

In this installment in my series describing a Git workflow for open source collaboration we'll look at the final step in the workflow, submitting your contribution to the project owner(s).

Create a GitHub Pull Request

Your develop branch in your fork now contains the code you want to contribute, so you now need to send a pull request to the project owner(s) asking them to accept your contribution. Go to the main page for your GitHub repo (the fork that you created and to which you just pushed), and click the pull request button, which looks like this:

[More]

In this installment in my series describing a Git workflow for open source collaboration we'll look at the workflow for developing code to be contributed back to the project (e.g., bug fixes, new features, etc.).

Add a Feature

After reading parts I and II your local repo is all set up and ready to go. Let's say you want to add a feature to the project. The first step is to create a topic branch for your changes. A topic branch is not a special type of branch from a technical perspective, it's just a regular Git branch, but I'm going to use that term to refer to a branch that you create for one specific purpose. It might be to fix a bug or to add a feature. This brings us to our first rule:

Rule #1 - All Changes Should Be Made in a Topic Branch

That's right. Never make changes directly in the develop branch, and never, ever, touch the master branch. If you want to add a feature you need to create a new topic branch for your feature. Let's call it newFeature and create it by issuing the command from within the develop branch:

You'll recall from the previous post that the -b option tells Git to create a new branch. Make some code changes and commit often. Don't worry about creating too many commits as you're going to squash them down before merging them back into the develop branch. One thing you want to keep on top of, though, is keeping your code up to date with the code in the main repo. If changes happen to code in the main repo you want to get those changes into your topic branch as soon as possible, to minimize the chances of merge conflicts later. This brings us to the second rule:

[More]

In this installment in my series describing a Git workflow for open source collaboration we'll look at the steps to get your local development environment ready to participate in the workflow.

Get Git and a GitHub Account

In order to make use of this workflow as described you'll need to have Git installed on your machine, you'll need a GitHub account, and you'll need to configure your machine to talk to GitHub. I wrote a blog post covering those topics, for folks on OS X, awhile back. If you are on another OS there are plenty of resources available.

Create a Fork

This post assumes that you're starting from scratch, so the first thing you'll need to do is create a fork of the main project repo on GitHub.

For the purposes of this post I'll be using the repo for ValidateThis, so go to the main GitHub repo for ValidateThis, which is located at http://github.com/ValidateThis/ValidateThis. Click the fork button which you'll see near the upper right-hand corner of the screen:

You'll see a message similar to this, telling you that GitHub is creating a fork of the repo for you:



Once the fork has been created you'll be taken to the repo page for your fork of the ValidateThis repo.

[More]

I found this out via a tweet from Mike Henke and then also saw it mentioned on the GitHub blog. Every year Git runs a survey of Git users to get feedback and help drive the future development of Git.

You can answer as many or as few questions as you like, and you can even return to the survey later and update your answers. The survey will be active until October 15th, and the results of the survey will be made public via the Git wiki after that. The survey can be found at http://tinyurl.com/GitSurvey2010, why not complete it today?

As some of you may know, I'm the lead developer on an open source project called ValidateThis. I changed the version control software that I'm using for the project from Subversion to Git almost a year ago, and I've been very happy with Git ever since. There was a bit of a learning curve to Git, particularly as I'd never really used the command line much, and it's pretty much required with Git, but that was actually one of the reasons for the switch - to give me the impetus to really learn how to work with Git.

I am lucky enough to have several contributors to the project, and they made me aware recently that the fact that the source is housed in a Git repository is interfering with their ability to make contributions. They all have plenty of experience working with Subversion, but Git is quite new to most of them. Simply learning the syntax of Git is no problem, but what many people find difficult, me included, is figuring out how to change their workflow, as working with Git can be quite different from working with Subversion. So I decided to do some research and come up with a proposal for a workflow for all of the contributors. We're going to give it a try and see how well it goes. If changes need to be made, we'll make them. My hope is that the workflow we devise is one that can be used by other open source projects as well, if they choose to do so.

I am going to describe this workflow in detail through a series of posts on my blog, this post being the first installment. The series will likely contain the following posts:

• Introduction
• Setting Up Your Local Environment
• Developing Code
• Submitting Code to the Project

[More]

I wrote a blog post awhile back about using Git rebase to squash a bunch of small commits into a single commit. I really like this approach as it allows me to commit frequently without having to litter my public repo with lots of meaningless commits. I've recently been researching Git workflows, trying to come up with a workflow for contributors to ValidateThis, and noticed that there's an easier way to start a rebase for all commits in a branch, which is generally what I need to rebase.

When I start working on a new feature, or even a bug fix, I generally start a new branch for it:

I then make my changes, committing frequently. When I'm ready to merge my changes back into the master branch I don't want all of those small, meaningless commits showing up, so I use get rebase to squash them. In the pervious article I discussed how I'd use git log to determine how many commits I wanted to rebase and then use git rebase -i HEAD~n, where n is the number of commits that I want to rebase. This is a useful feature if your commits are already in your master branch, but if all you want to do is rebase all of the commits in the current branch (newBranch in this example), then you can simply do:

Which tells Git to rebase all of the commits in the current branch that are not already in master. After issuing that command you can follow the steps as described in the previous article to choose which ones to squash and then to create a new commit message.