Page History

...

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 the main 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.

...

• Requires frequent merges from trunk into  into your feature branch to keep merge conflicts to a minimum. 
• May require period 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.

...

• 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 JiraJIRA. 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

...

$ 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

$ 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

$ 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

$ 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

...

• 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

$ 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