Open-Source Contributor's Guide to Using Git

Having re-started development of the Apache Lucene.NET project, we get asked quite often about the "right" way of contributing code. This is a quick-n-dirty guide for those who are new(ish) to git. Follow the guidelines below and your journey for contributing to Lucene.NET or any other open-source project (which is using git) will be as smooth as it can be.

Get the source code

Before you do anything at all, you will need to have the source code locally.

git clone <repository_location>

This will clone the remote repository to your local disk, and checkout the master branch by default.

You may also want to look at tools like GitHub for Windows, SourceTree and others. I personally use msysgit when on Windows, mostly the command line otherwise.

Fix a bug / add a feature

So you want to contribute code. First, create a local branch tracking the latest check-in to upstream:

git checkout -b <meaningful_branch_name> -t origin/master

I'm assuming origin/master to be the current development branch (that is: the upstream repository is called origin, and the development branch there is master). This is not always the case, so pay attention to the project guidelines.

Executing the above command will create a local branch, tracking the latest code from upstream. Make sure you name it properly (like feature-foo or bugfix-issue-131).

Naming your branch properly is super important - this is not an optional step!

Code away!

Make sure to always be in sync

Don't let your copy go stale. Fetch changes from upstream frequently, and keep your development branches up to date with it.

Always prefer to rebase, as opposed to merging with upstream. Merging often creates an additional noise that we would want to avoid.

git rebase origin master

This will update your current branch with the latest changes from upstream (again, assuming upstream is called origin in your local copy, and master is the current development branch).

Stashing

Sometimes you have some edits you don't want to commit, but also don't want to lose. When switching branches, or before doing a rebase, you will need to persist them somehow. Use stashing.

git stash

Recovering them later is done via

git stash pop

Read more here.

Squashing

In your branch, you may find yourself committing changes quite frequently. That's perfect!

However, to make your Pull Request as tiny and tidy as possible - please do squash all the commits you've made to your branch into one nice commit. Still, make sure to have all the details and reasoning documented within this one commit.

Squashing is a bit of a pro thing - here is a good guide about doing it right.

Pull requests

Before submitting a Pull Request (PR), make sure you have squashed and then rebased. This will keep your PR small and tidy, and allow much easier interaction with the community. It is also a lot easier for the maintainers to pull your changes in like that.

GitHub makes Pull Requests very easy and joyful, and you should use that. While Torvalds disagrees, who cares. We are all in for making a healthy development environment and I'm ok with him not being my role model for that...

In the Pull Request, please provide meaningful explanations on what was done, how and why. It is a place for discussions on those changes, and can also serve as documentation for our children and grandchildren to understand why we coded things the way we did. Or just for the senile developer in our team...

Before sending a PR though, please make sure to squash your changes, and then rebase with upstream - to minimize the chance of requiring a merge later, as well as to make sure nobody has already worked on the stuff you just did.

There's a great guide on GitHub on Pull Requests - do read it if you are new to the concept!

Merge / diff tools

Using the right diff / merge tool will save your day. There are many around, but personally I like Perforce's p4merge the most. Here's a gist on how to set it up with git.

Have fun, be nice

Open-source will only strive if we will be nice to one another, and respect contributor's time and effort. This doesn't mean we can't be critic about proposed changes - but we should always remember we only do this because its important, and fun.