Branching

The Main Branches

The Mapstraction Git repository contains two branches, each with an infinite lifetime ...

• master
• integration

The "master" Branch

The master branch at origin is a standard feature of Git. origin/master is the main branch, where the source code at the head always reflects a stable or production-ready stripe of the Mapstraction code.

The important things to remember about the master branch are ...

• Don't branch from master; only the integration branch branches from master
• Don't commit or merge to master; unless you're merging back a release; see Releasing

The "integration" Branch

origin/integration is the main branch where the source code at head reflects the latest changes destined for the next formal release.

When the source code in the integration branch reaches a point where a release of Mapstraction occurs, the changes in integration are merged back into master as part of the release process.

Other Branches

In addition to the main branches, master and integration, there are two other types of branch to assist in parallel development, prepare for releases and to help in fixing major problems or bugs. Unlike the main branches, these other branches are assumed to have a fixed lifetime and will probably be removed once they're no longer needed ...

• Feature Branches
• Release Branches

Feature Branches

• May branch from: integration
• Must merge back to: integration
• Naming convention: anything except master, integration or release-*

Feature branches are used both in day-to-day development, as well as handling pull requests as part of the Mapstraction release process; see Releasing for more information on this.

Creating A Feature Branch

When starting work on a new feature, say the implementation of support for a new mapping API, branch from the integration branch.

$ git checkout -b feature-new-maps-support integration

Merging A Finished Feature

When work is finished on the concept or implementation of a feature, they can be merged back into the integration branch and optionally deleted.

$ git checkout integration
$ git merge --no-ff feature-new-maps-support
$ git branch -d feature-new-maps-support
$ git push origin integration

Release Branches

• May branch from: integration
• Must merge back to: integration and master
• Naming convention: release-*

See Releasing for how release-* branches are used as part of the Mapstraction release management process.

Credits

Credit is due to Vincent Driessen's A Successful Git Branching Model, who managed to actually write down and make sense of the branching model that seemed so clear in my head but made my head hurt every time I tried to write it down.