=====
 GIT
=====

.. _git-branch-names:

Branch Names
============

We recommend the following naming schema for `git`_ branches which are
pushed to publicly accessible locations (local branches do, of course,
not have to conform to these recommendations):

.. digraph:: branches
   :caption: In the figure, ellipses designate commits, red boxes
             designate branches and green diamonds designate tags.

   fontname=Arial
   fontsize=11
   node [fontsize=11,fontname=Arial]
   edge [fontsize=11,fontname=Arial]

   rankdir=LR

   node [shape=ellipse]
   edge [dir=back]
   a -> b -> c -> d
   b -> h -> i
   d -> { e f g }

   edge [style=dashed,dir=forward]
   node [shape=box,style="filled",fillcolor="#fff0f0"]
   0.1 -> i
   master -> d
   f45 [label="feature-45"]
   f45 -> e
   b36 [label="bug-36"]
   b36 -> f
   wips [label="wip-something"]
   wips -> g

   node [shape=diamond,style="filled",fillcolor="#f0fff0"]
   r01 [label="release-0.1"]
   r01 -> b

Permanent Branches
------------------

``master``

  TODO

:samp:`{VERSION}`

  For branches in which released versions are maintained. Examples of
  :samp:`{VERSION}` are ``0.8``, ``0.22`` and ``1.0``.

Temporary Development Branches
------------------------------

.. important::

   Branches of this kind should be deleted (locally and remotely) once
   their contents has been verified and merged into the respective
   parent branch (usually ``master`` or a :samp:`{VERSION}`
   maintenance branch).

:samp:`bug-{ISSUE-NUMBER}`

  For branches in which fixes to particular known bugs are being
  developed. :samp:`{ISSUE-NUMBER}` should be the number of the issue
  tracking the bug in the issue tracker.

  These branches will participate in merge tests conducted by the
  continuous integration server.

:samp:`feature-{ISSUE-NUMBER}`

  For branches in which new features are being developed.
  :samp:`{ISSUE-NUMBER}` should be the number of the issue tracking
  the feature in the issue tracker.

  These branches will participate in merge tests conducted by the
  continuous integration server.

:samp:`feature-{NAME}`

  For branches in which new features are being developed when there is
  no corresponding issue in the issue tracker.

  These branches will participate in merge tests conducted by the
  continuous integration server.


  .. note::

     It is recommended to track new features in the issues tracker and
     use the previously described :samp:`feature-{ISSUE-NUMBER}`
     naming schema.

:samp:`wip-{NAME}`

  For branches which just store some unfinished and/or broken changes
  not related to a particular bug or new feature. This kind of branch
  is useful for storing unfinished work without triggering merge test
  on the continuous integration server.

  These branches will **not** participate in merge tests conducted by
  the continuous integration server.

.. _git-tag-names:

Tag Names
=========

.. important::

   Tag names must not clash with branch names. Therefore we recommend
   :samp:`release-{VERSION}` instead of just :samp:`{VERSION}` for
   tag names.

:samp:`release-{VERSION}`

  For tags which mark the point in history at which the release branch
  named :samp:`{VERSION}` diverged from the mainline history.