Git workflow and branching model

This document explains the branching model adopted by the CamiTK project.

It is based on the great steps of software development and freely inspired from “A successful Git branching model” by Vincent Driessen which describes a useful (and now very popular) workflow. A comparative description from Atlassian can be also an interesting read.

To improve your knowledge on Git we advise you to check some of these references:

• the online “Pro Git” book
• the “Visual Git Reference”
• or “git - the simple guide” Pro Git book

And to check your competencies and git technical knowledge, we highly recommend the totally interactive “Learn Git Branching” tutorial website

Gitlab git repository to coordinate developments

We base all our git management on gitlab. You can check everything that is going on on our gitlab instance. It allows synchronisation for everybody on objectives to reach (new features, bug fixes, releases, hotfixes, etc.). It holds the history of all CamiTK Community Edition development.

There are two main permanent branches on our Git system:

• The production/stable release branch (master): it is updated with the new stable release (including hotfixes)
• The current development branch (develop) : it is used when working on new features and general bug fixes.

We mainly follow what is called the gitflow workflow.

To get a more convenient way for using our source code management, we apply a merge request process based on a new branch created from develop (or exceptionally from master in cases of hotfixes). We don’t use a forking model with pull request.

Branching model

On the origin (main) repository in our gitlab instance, two branches are therefore permanent (master and develop) and others are temporary branches (for releases, hotfixes, new features and bug fixes).

The gricad’s remote repository is just a place where we manage our collective development. The figure below represents our git branching model in action.

The big repository on top is our gitlab instance remote repository (aka git origin). To start any work or contribution on the code, it has to be cloned locally. The two smaller repositories below the origin repositories represent local repositories that developers have cloned and pulled on their computer.

CamiTK develop and master permanent branches

develop branch

develop is where everyone can find the source code in last development state. All the standard development activities come from this branch and are merged back to this branch. Note that develop is not broken easily as only branches that have passed all the continuous integration pipeline stages (at least configure, build, test) can be merged. It is therefore protected and only maintainers can merge to develop once everything seems correct.

master branch

master is where released versions are stored. The latest master is always the same as the latest stable version. A tag is defined for every release or hotfix that equals the CamiTK Community Edition version number. This is the integration branch, no one can push on this branch except temporarily authorized maintainers. If you want to get the latest stable version, you can also clone from this branch (or from the release tag).

How to add a new feature or fix a bug

Since CamiTK 5

CamiTK Community Edition development process

The CamiTK Community Edition development process is essentially based on issues, issues and… issues.

Adding a new feature or fixing a bug should always start from an issue described on our gitlab instance.

This have many advantages:

• all development are guaranteed traceability.
• all development are guaranteed to be opened to everyone.
• it speeds the process up (just two clicks! )
• there is no special needs for a branch naming convention.
• discussions about the issues are visible by everyone on the issue dedicated page and it is possible for everyone to give their inputs
• discussions about the code are also visible in the merge request dedicated page and it is possible for everyone to give their inputs

Basically, the process is very simple:

1. always starts by creating a new gitlab issue. Click on New issue and use the corresponding templates (bug, feature or technical feature, see below). You may try to assign specific type and track labels (see below).
2. When you are ready to contribute, create a new merge requests from the issue page. It will therefore be automatically linked to the issue. To , by clicking on the issue Create Merge Requests button.

Issue types

There are three types of issues:

• bug: the issue should describes the bug as precisely as possible. The issue is tagged with the Bug label. Once the bug is confirmed by at least another contributor the label is changed to Bug Confirmed and the track label is assigned.
• feature request: the issue is a new feature. It should be taged with the Feature Request label
• technical feature: this is for all other issues (i.e., development that does not concern new features or bug fixes). It is generally used when some work is required on CamiTK core library or dependency. In this case, the track label is of utmost important.

Issue tracks

All issues should end up with a track tag. A track will help bug and feature triage. It will also help to define project sprint priorities.

8 tracks are defined in CamiTK Community Edition:

• Track Code Maintainability
• Track Continuous Integration
• Track Debugging
• Track Dev Support
• Track End User Experience
• Track Knowledge Management
• Track Prototyping Experience
• Track Technology Integration

See the label page for a complete description.

An issue starts generally with a Track None label. It helps a lot contributors and maintainers to set the proper label. In doubt, as the maintainers.

Feature and bug fixes branches and merge requests

The feature and bug fixes branches created by this process are used to receive the actual development works. Once the merge requests is created on the gitlab repository, just git fetch and git checkout name-of-the-branch-deduced-from-the-issue-title.

The continuous integration pipeline is automatically started on a new branch and activated each time you push your branch to origin. Pushing to origin will also makes it available for other developers to check on the corresponding merge request page.

For instance the issue of id 42 titled Update extension using the CamiTK cep store will create:

• a new branch 42-update-extension-using-the-camitk-cep-store (which you can pull locally to start working on)
• a new merge request called Draft: Resolve "Update extension using the CamiTK cep store"

Note on the release process

This section briefly describes how git is used to create a new release.

release branch

CamiTK Community Edition follows the semantic versionning system (SemVer).

A new release branch starts from the current develop branch when the maintainers and contributors decide that it is ready for release. It can be understood as a feature freeze branch of develop. Some extra check are done on the develop and release branch before merging it to the master branch.

Release branches are named release/x.y.0 where x.y corresponds to the release major and minor version (release/5.1.0 for example). A release branch name should end up with .0.

If a bug is fixed on the release branch, it has to cherry picked and added to the develop branch. But at this stage no new features from the develop branch are pushed to the release branch.

Once it is ready for distribution and production, it is merged directly to the master. A corresponding release tag is then created on the master branch and the release branch is deleted.

Release tags are named x.y.0 and should corresponds to the release branch name.

Hotfix branches

Hot fixes come from the necessity to produce a bug fix to an already released version. These developments will involve the creation of a specific hotfix branch creation that comes from the master branch, based on the release tag on which the hotfix must be applied.

Hotfix branches are named hotfix/x.y.x where x.y corresponds to the release major and minor version and z to the incremented patch version, one increment per hotfix (hotfix/5.1.3 for example). A hotfix branch name should start with a patch number equals to 1 and should never end up with 0.

Corrective commits are made on the hotfix branch and cherry picked to the develop branch.

Once it is ready, the hotfix branch is merged back to the master branch. A corresponding release tag is then created on the master branch and the hotfix branch is deleted.

Hotfix tags are named x.y.z and should corresponds to the hotfix branch name.