Using Git With Virtuoso Open-source

Introduction

Due to the nature of its development cycle which includes several active development versions we apply a slightly more involved git usage paradigm as compared to smaller OpenLink projects.

The main difference is that instead of a single devel branch we have more than one which means a slightly more complicated management of releases and hot fixes.

Repository Setup

We use a moderated development model where there is one "official" repository that is private. Only the administrator can push changes to this repository. Developers work in their own clones of the repository and send merge requests to the administrator (details of this procedure are not clear yet. We might want to setup or use a web frontend.)

Branches

Our development model is based on the git workflow originally presented by Vincent Driessen. We have a master branch which always reflects the current release, development branches for each version of VOS, stable branches for each major release of VOS, feature branches and release branches. The only difference to the mentioned git flow system is that we have more than one stable branch - where git flow (and other smaller OpenLink projects) uses branch master for tracking the current stable state, we use branches prefixed stable.

Let us look at the branches in detail.

The main branches

We have a set of main branches with an infinite lifetime, its number depends on the number of currently developed versions of VOS. Here we assume that we work on VOS6 and VOS7 in parallel, VOS6 being the production version. This results in two main development branches:

The branch develop/6 always reflects the latest state in active development of the VOS6 series. New features are integrated here.

In addition we have one branch for each major release of VOS:

These are branched off their respective develop branches whenever a new major release is about to be created.

The master branch always matches the latest stable release; release tags are only created on the master branch.

Feature branches

New features are developed in feature-branches (sometimes called topic branches). Feature branches typically have the prefix feature/ and should always be branched off a development branch:


$ git checkout -b feature/myFeature develop/6

Once the feature is done it should be merged back into the originating branch:


$ git checkout develop/6
$ git merge --no-ff feature/myFeature
$ git branch -d feature/myFeature

The --no-ff flag causes the merge to always create a new commit object, even if the merge could be performed with a fast-forward. This avoids losing information about the historical existence of a feature branch and groups together all commits that together added the feature.

For the time being we also allow features to be branched offs table major release branches for convenience. This, however, results in a slightly more complicated procedure. First we have to branch off the stable branch:


$ git checkout -b feature/myFeature stable/6

Once the feature is done it is merged back into the stable branch:


$ git checkout stable/6
$ git merge --no-ff feature/myFeature

But the feature also has to be merged into the devel branch before being deleted:


$ git checkout develop/6
$ git merge --no-ff feature/myFeature
$ git branch -d feature/myFeature

Tagging a release

A release is always tagged from a stable branch. Since master should always reflect the current recommended stable version of VOS it does not need to be updated on every release. Imagine for example a bugfix release of VOS6 when VOS7 has already been released.

As soon as a develop branch has reached a stable state fit for a release a release branch is created in which the rest of the release preparation like version bump, ChangeLog? updates, and so on are done:


$ git branch -b release/6.2.2 develop/6

Once the branch is done it is merged back into the originating branch and the corresponding stable branch:


$ git checkout branch develop/6
$ git merge --no-ff release/6.2.2
$ git checkout stable/6
$ git merge --no-ff release/6.2.2

Then the release is tagged from the stable branch:


$ git checkout stable/6
$ git tag -s v/6.2.2

In case this new release is the latest recommended version the release branch also has to be merged into master.


$ git checkout master
$ git merge --no-ff release/6.2.2

Due to the nature of VOS development two develop branches may diverge a lot making it virtually impossible to merge one into the other. Thus, if the release introduces a new major VOS version, master needs to be updated in a special way, essentially throwing away all the changes from the old major version. This can be achieved by specifying a special merge method:


$ git checkout master
$ git merge -Xtheirs --no-ff release/6.2.2

And finally the release branch can be removed:


$ git branch -d release/6.2.2

Hotfix Releases

Sometimes there is the need to release a hotfix. A hotfix is a small bugfix release which does not necessarily be based on the latest stable release. If version 6.2.0 was the latest stable release some people might still use 6.1.3 because they fear the maintenance hassle with updating to another major version. Thus, if a bug is found in 6.1.3 a hotfix release 6.1.4 needs to be released. This is done by branching off a tag:


$ git checkout -b hotfix/myFix v6.1.3

Once the fix is done it might require merging back into the stable and/or the develop branch, depending on whether the fix still applies in the newer versions:


$ git checkout stable/6
$ git merge --no-ff hotfix/myFix
$ git checkout develop/6
$ git merge --no-ff hotfix/myFix

Tagging a hotfix release is a little different from normal release tagging as described above. Since master is not touched we tag the release directly in the hotfix branch and then delete it:


$ git checkout hotfix/myFix
$ git tag -s v/6.1.3
$ git branch -d hotfix/myFix

References

See also: