---+ Using Git With OpenLink Software's Open-Source Projects

%TOC%

---++ Introduction

By design =git= can be used in a variety of ways. In fact it allows so many ways
of managing ones code that it is easy to mess everything up. Thus, it is
important to stick to fixed policies and rules when using a git repository
collaboratively. This document states the setup and the policies used with the
VOS git-repository.

---++ Repository Setup

We use a moderated development model where there is one "official" repository
that is maintained by OpenLink Software. Only OpenLink can push changes to this
repository. Developers work in their own clones of the repository and send merge
requests or patches 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
[[http://nvie.com/posts/a-successful-git-branching-model/][nvie]]. We have a
master branch which always reflects the current release, a development branch,
stable branches for each major release, feature branches, and release branches.

All the procedures described below can also be performed via the
[[https://github.com/nvie/gitflow][git-flow extension]].

Let us look at the branches in detail.

---+++ The main branches

We have two main branches with an infinite lifetime.

   * The branch =develop= always reflects the latest state in active development. New features are always integrated here.
   * 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 the development branch:

<verbatim>
$ git checkout -b feature/myFeature develop
</verbatim>

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

<verbatim>
$ git checkout develop
$ git merge --no-ff feature/myFeature
$ git branch -d feature/myFeature
</verbatim>

The <tt>--no-ff</tt> 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.


---++ Tagging a release

A minor release is created from a stable version branch like =master=. A release
branch is created in which the rest of the release preparation like version
bump, ChangeLog updates, and so on are done:

<verbatim>
$ git branch -b release/1.2.2 master
</verbatim>

Once the branch is done it is merged back into =master=:
<verbatim>
$ git checkout branch master
$ git merge --no-ff release/1.2.2
</verbatim>

It also has to be merged into the development branch (this might lead to
conflicts which need to be resolved):

<verbatim>
$ git checkout develop
$ git merge --no-ff release/1.2.2
</verbatim>

Then the release is tagged from =master=:

<verbatim>
$ git checkout master
$ git tag -s v/1.2.2
</verbatim>

and finally the release branch can be removed:

<verbatim>
$ git branch -d release/1.2.2
</verbatim>



---+++ Hotfix releases

Bug fixes that will go into a minor release (and as such are not considered a
feature to be branched off the =develop= branch) need to be branched off the
=master= branch.

<verbatim>
$ git checkout -b hotfix/myFix master
</verbatim>

Once the fix is done it is merged back into the =master= branch:
<verbatim>
$ git checkout master
$ git merge --no-ff hotfix/myFix
</verbatim>

In case the fix also applies to the latest development version the branch has
also to be merged into the =develop= branch before being deleted:

<verbatim>
$ git checkout develop
$ git merge --no-ff hotfix/myFix
$ git branch -d hotfix/myFix
</verbatim>


---++References

   * [[http://virtuoso.openlinksw.com/dataspace/dav/wiki/Main/GitQuickstartTips][Git Quickstart &amp; Tips]] [virtuoso.openlinksw.com]
   * [[http://progit.org/book/][ProGit - Online-Book on Git Usage]]
   * [[http://help.github.com/][GitHub Help]]