Photo from Chile

A Git Workflow for Open Source Collaboration - Part IV - Submitting Contributions

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:


A Git Workflow for Open Source Collaboration - Part III - Developing Code

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:

view plain print about
1git checkout -b newFeature

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:


A Git Workflow for Open Source Collaboration - Part II - Getting Started

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 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.


A Git Workflow for Open Source Collaboration - Part I - Introduction

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