Detailed Description of the Workflow
Git is a distributed VCS and so allows a developer to have their own copy of any other repo out there. Yet it makes life easier if there is still an authoritative repo that can be used to get the latest changes. This is sometimes called a central “truth” repo. We will refer to it as origin, since this name is familiar to all Git users. In some places, we also refer to it as the main repo.
Each developer pulls changes from origin. Besides that it’s also possible to pull from other developers, for example if they want to work together on a new feature.
Branches in Git are very lightweight. Unlike Perforce, git branches are outside of the file hierarchy. Switching between branches can be done in the same working directory and is extremely quick since only the files that are different between the branches are touched. Branches can exist locally in the developer’s repository without existing in the main repo. All this fundamentally changes the way one approaches version control.
There are good introductions to Git branches available, e.g. chapter 3 from the “Pro Git” book.
Vincent Driessen suggests a branching model (see this blog entry) that clearly separates ongoing development work from preparation of release and already released versions. Since his description very nicely outlines the conditions and merge implications of the different branches I borrow from him for this description.
The central origin repo always holds two major branches:
- master
- develop
Occasionally (e.g. during preparation for a release) it might hold additional temporary branches that get deleted after the temporary branch got merged to master or develop.
[JohnT: what is lost by 'deleting' a branch? Can we still tell who made a change and what task they were working on?
Answer: if the branch got merged into master or develop prior to deleting then the only thing that changes by deleting a branch is that the name of the branch no longer appears in the list of available branches. All commits that were part of the branch and that got merged into master or develop are still there.]
Besides the master and develop branch there are four other types of branches:
- Feature branches
- Release branches
- Hotfix branches
- Support branches
Each of these branches have a specific purpose and are bound to strict rules as to which branches may be their originating branch and which branches must be their merge targets. We will walk through them in a minute.
The following diagram from Vincent Driessen might help in understanding the Git Flow branching model:
The master branch always holds the latest released version. No direct commits are allowed to it; the only way new commits end up on the master branch are through merges from a release or hotfix branch.
The develop branch contains the latest development code for the next release. No direct commits are allowed to the develop branch; all new commits that end up on the develop branch are through merges from either a feature, release, or hotfix branch.
Feature branches (also known as “topic branches” in the git community) are used to develop new features for the upcoming or a distant future release. When starting development of a feature, the target release in which this feature will be incorporated may well be unknown at that point. The essence of a feature branch is that it exists as long as the feature is in development, but will eventually be merged back into develop (to definitely add the new feature to the upcoming release) or discarded (in case of a disappointing experiment).
We distinguish beetween regular feature branches that exist only locally but not on origin, and long-lived feature branches that exist on origin.
May branch off from: develop, release, or long-lived feature branch
Must merge back into: same branch it got branched off
Branch naming convention: JIRA task number or descriptive name of branch, e.g. feature/FWR-9876 or feature/PalasoWs
A regular feature branch is used for a bugfix or to develop one aspect of a new feature. When the bug is fixed the change is uploaded to Gerrit and eventually merged onto the destination branch.
May branch off from: develop
Must merge back into: develop
Branch naming convention: JIRA task number or descriptive name of branch, e.g. feature/FWR-9876 or feature/PalasoWs
A long-lived feature branch is used to develop a costly new feature or to share work on a feature. Changes in Gerrit will be merged onto the long-lived feature branch. This allows to get a feature into shape without de-stabilizing the destination branch. Any work will be done in a short-lived feature branch which is based on the long-lived feature branch. After uploading the change to Gerrit it will get merged onto the long-lived feature branch.
May branch off from: develop
Must merge back into: develop and master
Branch naming convention: release/* where * is the new version number
Release branches support preparation of a new production release. They allow for last-minute dotting of i’s and crossing of t’s. Furthermore, they allow for minor bug fixes and preparing meta-data for a release (version number, build dates, etc.). By doing all of this work on a release branch, the develop branch is left clear to receive features for the next big release.
May branch off from: master or a support branch
Must merge back into: develop and master (or a support branch)
Branch naming convention: hotfix/* where * is the version number (tag) of the version we’re fixing.
Hotfix branches are very much like release branches in that they are also meant to prepare for a new production release, albeit unplanned. They arise from the necessity to act immediately upon an undesired state of a live production version. When a critical bug in a production version must be resolved immediately, a hotfix branch may be branched off from the corresponding tag on the master branch that marks the production version. When the critical bug is fixed the hotfix branch is merged back into the master (and develop) branch to create a new version of the product for release, and master is tagged with this new version number at this point.
The essence is that the work of team members (on the develop branch) can continue, while another person is preparing a quick production fix.
May branch off from: master
Must merge back into: develop
Branch naming convention: support/* where * is the version number (tag) of the version we’re branching off.
These are long-lived branches, that don’t get deleted.
Support branches are branched off of the master branch if we need to fix a problem in an earlier released version. An example would be if we release FW 7.0 and then decide that we need to release another version of FW 6.0. In this case we would create a support/6.0 (based on the 6.0 tag on master), fix the problems and tag the tip of support/6.0 as 6.0.1.