Git Branches

Git's branching model is very flexible and if you're not careful you can get yourself into trouble with a mess of branches and an unreadable commit history. This document explains Sirikata's standard branches, how to operate on them, and how to add more branches for long-lived feature development.

Main Branches

The two main branches are master for unstable development and staging for stabilizing code for releases. Here's how to use these branches:

• A small, important bug fix - commit to staging.
• Other bug fixes - these aren't critical to stability and if large enough may be harder to be certain won't cause problems. Commit to master.
• New features - commit to master.

In other words, commits that contribute to stability should go to the staging branch

How do commits on one branch make it into the other? For the two main branches there are two ways:

• Start preparation for new release - merge master into staging. The new release begins in unstable form and bugfixes bring it into stable form.

 git checkout staging && git merge master

• Pull bug fixes back into development version - merge staging into master. This can be done as often as necessary -- it won't be required after every bug fix on staging but probably after many of them. At a minimum, it should occur before a new release is started.

 git checkout master && git merge staging

The direction of merge is important as it helps indicate why the merge occurred. Be sure you merge in the correct direction.

Releases

Releases are tags, not branches. They are simple tagged directly off the staging branch when the release is considered ready.

Feature Branches

Sometimes you need to work on a feature for awhile before it should even land in master. This might be because it may cause build problems (e.g., a new dependency) or stability problems (e.g., a big change to a core class). In this case, you should use a feature branch.

Feature branches should always be developed off of master since they are considered even less stable.

• Start a feature branch

 git checkout -b myfeature master

• Get updates from master to keep up with other development (on myfeature)

 git merge master

• Finish development on a feature (or its stable enough to go into master)

 git checkout master && git merge myfeature

New plugins are a good candidate for a new feature branch: while the plugin is setup and tested across platforms, it can live on a feature branch. However, because plugins don't have to be loaded, as soon as the build works properly it can be developed in master since it won't affect anyone if it is buggy. You could maintain the branch if you prefer to keep your plugin development clear, but be sure it eventually gets merged back in to master.

Summary

This model keeps the progression of code from unstable to stable clear.

• The most unstable goes on feature branches.
• When they are more stable, feature branches are merged into master.
• Stable releases are created by merging master's less stable commits into staging.
• Stable releases are tagged from staging.

Similarly, fixes on more stable branches make it back to less stable branches by merging in the opposite direction.

• Important bug fixes go on staging and are merged back into master.
• Normal development occurs on master and is merged back into feature branches.