Branch on Feature

This page describes a simple git workflow called branch-on-feature, which we will be using for TeamGroove. It is a basic technique that can be used on its own or even as part of a bigger, more elaborate workflow such as gitflow.

The key idea is that we have a long-lived integration branch, which might be called something like develop. The team members iteratively implement user stories onto that central branch, so the project history can be seen as a series of changes on this branch. And in this approach, each user story gets implemented in its own short-lived branch like this:

1. SELECT: The developer picks a feature or user story to implement.
2. BRANCH: They branch from develop to create a new branch - called a feature-branch.
3. IMPLEMENT: Then they make the changes they need to in the feature-branch to implement the user-story.
4. REVIEW: The changes are then reviewed and tested by some other team members - usually via a so-called pull request. This might trigger off several rounds of bug fixes.
5. MERGE: Once the team is happy, the feature-branch is merged into the develop branch - usually by 'completing' the pull request in a web browser. The feature-branch is usually discarded at this point.
6. DONE: And when the feature has made it onto the integration branch, the user story is done.

Practical Considerations

Iteratively implementing user stories in their own short-lived branches is the essence. But when you put this into practice, you quickly discover that this isn't a full picture. A typical first stumbling block is how to name branches. In branch on feature there are often a lot of little branches and it's helpful if the team has a system for making up names for feature-branch that say something useful. For example, a user story for the v0.1 milestone that implements the user-story New Drop Downs with id 123 might be named v0.1/123_new_drop_downs.

Note: some teams like to include the sprint name e.g. sprint06/new_drop_downs. I found that it caused extra work when stories overran sprints. So these days I prefer the first half of the name to relate to the version number, which is much more robust and more informative when it comes to making a release.

The second stumbling block is "merge conflicts". When several team members are working on a project, it is not uncommon that a particular file gets altered in two concurrent user stories. Sometimes git can resolve this potential conflict on its own. When it can't it flags the file (or files) involved as having a merge conflict and the programmer is obliged to resolve it.

Merge conflicts can be quite complicated and time-consuming to fix. Part of good project hygiene is to keep feature-branches small and short-lived, which reduces the frequency of conflicts. And if a feature-branch lasts for more than a few days, its a good idea to regularly merge in from the develop branch so that you only have a few merge conflicts to resolve.

Merge Back into the integration branch

Feature-branches make working independently a breeze. But sooner or later you have to bring the contents of the feature-branch into the integration branch. There are two common ways to do this. [1] You can do the merge locally on your machine and then push develop to the central repo. [2] Alternatively you can use pull requests, which do the merge on the central server.

In the case when you do the merge on your local machine, the trick is to ensure that your integration branch is up to date. If you do not, then your local copy of the integration branch may lag the central integration branch and, when you try pushing your local develop you get a complaint. Keeping your develop branch up to date with the central develop is not that hard. Here's a typical routine:

- A team member checkouts (switches to) the integration branch `develop`
- Then they pull from the `develop` branch to bring the local copy up to date 
- They fix up any merge conflicts and repeatedly pull-and-fix until all the problems are fixed
- Push the fixed result back to git
- Then they merge from the feature branch

5. They then complete the pull-request, usually by clicking a button on a web page, which will perform the merge on the central server.
6. Finally they switch to the develop branch and bring their local version up to date with a fast-forward.