The Git feature branch workflow is a simple, yet powerful way to develop new features in an encapsulated environment while at the same time fostering collaboration within the community. The idea is create short-lived branches where new development will take place and eventually merge the completed feature branch back into trunk. A short-lived branch could mean anywhere from several days to several months depending on the extent of the feature and how often the branch is merged back into trunk.

Feature branches are also useful for changes which are not necessarily considered to be new features. They can be for proof-of-concept changes or architectural changes which have the likelihood of destabilizing trunk.

Benefits

  • Allows incremental work to proceed without destabilizing the main trunk of source control.
  • Smaller commits means smaller and clearer code reviews. 
  • Each code review is not required to be fully functional allowing a more agile approach to gathering feedback on the progress of the feature.
  • Maintains Git history and allows for code to be backed out easily after merging.

Drawbacks

  • Requires frequent merges from trunk into your feature branch to keep merge conflicts to a minimum. 
  • May require periodic merges of the feature branch back into trunk during development to help mitigate frequent merge conflicts.
  • No continuous integration coverage on feature branches. Although this is not really a drawback since most feature branches will break some aspects of CI in the early stages of the feature.

Guidelines to Follow

The following simple rules can help in keeping Ambari's approach to feature branch development simple and consistent.

Branch Creation

  • When creating a feature branch, it should be given a meaningful name. Acceptable names include either the name of the feature or the name of the Ambari JIRA. The branch should also always start with the text branch-feature-. Some examples of properly named feature branches include:
    • branch-feature-patch-upgrades
    • branch-feature-AMBARI-12345

Branch Management

  • Every commit in your feature branch should have an associated AMBARI-XXXXX JIRA. This way, when your branch is merged back into trunk, the commit history follows Ambari's conventions. 

  • Merge frequently from trunk into your branch to keep your branch up-to-date and lessen the number of potential merge conflicts.

  • Do NOT squash commits. Every commit in your feature branch must have an AMBARI-XXXXX association with it.

Review Board Process

  • Every commit being made to the feature branch must still go through the code review process. As such, it should have an associated AMBARI-XXXXX JIRA.
  • The commits, however, do not need to be "fully functional". Since the goal of the feature branch is to make smaller, iterative updates, the commit may cause another area of the product to be temporarily broken.
  • Unit tests are not required for feature branch commits. However, they are required before merging the feature back into trunk. At the very least, at least 1 feature branch commit must include the test coverage which exercises the changes being made in the branch.

Branch Removal

  • Once a feature has been completed and the branch has been merged into trunk, the branch can be safely removed. Feature branches should only exist while the work is still in progress.

Approach

The following steps outline the lifecycle of a feature branch. You'll notice that once the feature has been completed and merged back into trunk, the feature branch is deleted. This is an important step to keep the git branch listing as clean as possible.

 

Creating the Feature Branch
$ git checkout -b branch-feature-AMBARI-12345 trunk
Switched to a new branch 'branch-feature-AMBARI-12345'

$ git push -u origin branch-feature-AMBARI-12345
Total 0 (delta 0), reused 0 (delta 0)
To https://git-wip-us.apache.org/repos/asf/ambari.git
 * [new branch]      branch-feature-AMBARI-12345 -> branch-feature-AMBARI-12345
Branch branch-feature-AMBARI-12345 set up to track remote branch branch-feature-AMBARI-12345 from origin by rebasing.

  • Branch is correctly named

  • Branch is pushed to Apache so it can be visible to other developers

 

Committing to Your Feature Branch
$ git checkout -b branch-feature-AMBARI-12345 trunk
Switched to a new branch 'branch-feature-AMBARI-12345'

$ git add <some-file>
$ git commit -m 'AMBARI-28375 - Some Change (me)'

$ git add <some-file>
$ git commit -m 'AMBARI-28499 - Another Change (me)'

$ git push

  • Each commit to the feature branch has its own AMBARI-XXXXX JIRA

  • Multiple commits are allowed before pushing the changes to the feature branch

 

Merging Trunk into Feature Branch
$ git checkout branch-feature-AMBARI-12345
Switched to branch 'branch-feature-AMBARI-18456'
 
$ git merge trunk
Updating ed28ff4..3ab2a7c
Fast-forward
 ambari-server/include.xml | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 ambari-server/include.xml

  • Merging trunk into the feature branch often (daily, hourly) allows for faster and easier merge conflict resolution

  • Fast-forwards are OK here since trunk is always the source of truth and we don't need extra "merge" commits in the feature branch

 

Merging Feature Branch Into Trunk
$ git checkout trunk
Switched to branch 'trunk'
 
$ git merge --no-ff branch-feature-AMBARI-12345
Updating ed28ff4..3ab2a7c
 ambari-server/include.xml | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 ambari-server/include.xml

No Fast-forwards

Notice that the --no-ff option was provided when merging back into trunk. This is to ensure that an additional "merge" commit is created which references all feature branch commits. With this single merge commit, the entire merge can be easily backed out if a problem was discovered which destabilized trunk.

  • The feature is merged successfully with a "merge" commit back to trunk
  • This can be done multiple times during the course of the feature development as long as the code merged back to trunk is stable

 

Deleting Your Branch
$ git checkout trunk
Switched to branch 'trunk'
 
$ git branch -d branch-feature-AMBARI-12345
Deleted branch branch-feature-AMBARI-12345 (was ed28ff4).
 
$ git push origin --delete branch-feature-AMBARI-12345
To https://git-wip-us.apache.org/repos/asf/ambari.git
 - [deleted]         branch-feature-AMBARI-12345
 
$ git remote update origin --prune
Fetching origin
From https://git-wip-us.apache.org/repos/asf/ambari
 x [deleted]         (none)     -> branch-feature-AMBARI-56789

  • Cleanup the branch when done, both locally and remotely

  • Prune your local branches which no longer track remote branches