CamiTK Git Branching Model
Here, we see what is the adopted branching model for the CamiTK project. It is based on the great steps of software development and freely inspired from nvie1 which is describe a usefull workflow. A deep description can be found on this site2 too. To improve your knowledge on Git you can consult some of these references like the online Pro Git book3, a visual reference4 or this guide5.
Central Repository to Coordinate Development¶
We maintain a central repository, which is not central as SVN can be, but as it allows synchronisation for everybody on objectives to reach (releases, hotfixes, common work, etc.). It is the common history of CamiTK development.
We structured branches on our Git system as :
- Production release
- Feature conception
- Release improvement via hot fixes
- Common developments
We mainly follow what is called the gitflow workflow, check this quick and illustrated explanation.
To get a more convenient way for using our scm, we apply a merge request system based on a forked repository, and all the work below described is deported on a forked repository. Thus, our central repository contains only two branches :
- develop which is the default branch
To apply the below described branch system we have to fork initial repository. To do this see this page : Contribute to CamITK. After you have forked the initial repository you will get your own central depot.
Working with depot¶
At this central depot, some of these branches are permanent (Master and Develop) and others are temporary (Releases, Hotfixes and Features) branches. In other side, some branches may only exist on the local working tree of a developer or group of developers and can’t be viewed on the central repository. That is mean some sub-team can work in parallel out of the main development flow. After their work is in a final state, they may want to merge back or create a new repository that they own. It’s up to them.
The repository is just a place where we manage our collective development. The picture below represent how the repository is structured. The two little repositories under the big one are local repositories, as you can have on your computer. The way you choose to develop with Git is depending on what you want to do. In the rest of this document we consider the CamiTK team point of view.
The big one is the repository you will clone when you want to participate in the development which is the one you forked. For you, this is the remote repository. We describe it as the “origin”. This name prefix the branch name, for instance, origin/develop is the develop branch on the remote repository. Actually, origin is used to make an alias for the complete path to the remote branch at the remote repository. Thus, in the rest of this document, if you read only the branch name without origin it will stand for the local branch, otherwise it will be the remote branch of what we talk to.
As we just see the global structure, let’s go on specific description of each branch.
Develop and master branches¶
Origin/develop is where everyone can find the source code in last development state. All the standard development activities come from this branch and merge back to this branch. Thus, if you want to make new feature you checkout the origin/develop to a feature branch on your local work-tree. If some improvements will be made on the origin/master branch they have to be merged back to origin/develop in order to keep this branch up to date with all new development.
Origin/master is where released versions or Hotfixes are stored. A tag is defined for every release or hotfix. This is the integration branch, no one can push on this branch except authorised developers. If want to get the latest stable version, you can clone from this branch.
The feature branches are for making effective development works. It is the developer job to create it on his local work-tree from the develop branch. Thus, the development work is done without improving integration risk on develop branch and with more flexibility for the developers itself on its local work-tree. When the work is done feature branch is merged back to develop branch and pushed on the origin/develop. The case in which developers collaborate on a huge feature is planned. Our branching model allows developers to push a feature branch to share it with others over the referential.
The release branch is visible from all of the referential repository. Some works from all team have to be done for the release can be distributed. While a release branch is open features are freezing and only debug can be performed and committed on this branch and back to the develop branch. When the final state of the release is reached all these works are committed back to the develop branch and on the master branch. A tag is set onto the master and the develop branch. After that the release branch is deleted.
Hot fixes come from the necessity to produce a correction to make release version already published stable. These developments will involve a hotfix branch creation that comes from the master branch, based on the release tag on which the hotfix must be applied. Corrections works are made and hotfix branch is merged back to the master branch with a hotfix tag and the develop branch too.
Here is the naming conventions adopted In CamiTK team to name branches At the creation.
- If the features was declared as a story In CamiTK agile management system or gitlab: the branch should be named feature/# (feature/#321 for example). Note: if the new feature was opened on bugzilla, first create an issue in gitlab.
- If the new feature was not declared as a story, the branch should be named feature/XXX where XXX is a comprehensible (although rather short) description (e.g., feature/connect-to-camitk-store).
- Bug fix:
- If the bug was opened on bugzilla, the branch should Be named bug/# followed directly by the bugzilla bug id (e.g., bug/#181). Note: an artifact in gitlab should also has been created.
- If the bug was not opened on bugzilla, the branch should Be named bug/XXX where XXX is a comprehensible (although rather short) description (e.g., bug/parallel-build).
- Hotfix: the branch should be called hotfix/ (hotfix/4. 0. 1 for example).
- Release: the branch should be called release/\< (release/4. 0. 0 for example)
- Tag: Use tag to add a label to the commit that correspond to the release or hotfix (e.g., for a release: 4.0.0 or 4.1.0, and for a hotfix: 4.0.1 or 4.0.2)