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
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
- 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
trunkinto 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.
- 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:
- Every commit in your feature branch should have an associated
AMBARI-XXXXXJIRA. 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-XXXXXassociation 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
- 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.
- 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.
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.
Branch is correctly named
Branch is pushed to Apache so it can be visible to other developers
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 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
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
Cleanup the branch when done, both locally and remotely
Prune your local branches which no longer track remote branches