========================
 Continuous Integration
========================

Jobs for one Project
====================

.. note::

   TODO generic naming conventions including ``-windows`` suffixes
   etc.

   I think flier has written down something, but CLF's ci server is
   down.

Common Jobs
-----------

In the following section, :samp:`{NAME}` refers to the name of the
project to which the mentioned jobs belong. An example of such a name
would be ``rsb-cpp``, referring to the C++ implementation of :ref:`RSB
<rsb>`.

:samp:`{NAME}-trunk`

  TODO

:samp:`{NAME}-trunk-merge-simulator`

  .. seealso::

     :ref:`git-branch-names`
       For recommended names for feature branches.

  The task of this job is simulating merges of feature branches into
  the ``master`` and reporting any problems that may occur. The kind
  of problems that may be detected by this job include:

  Merge Conflicts

    When the ``master`` branch has changed since a feature branch has
    been created, it may no longer be possible to merge the feature
    branch back into the ``master`` branch without conflicts.

  Build Problems

    Due to errors in the feature branch or changes in the ``master``
    branch, the result of merging the feature branch into the
    ``master`` branch may no longer build.

  Test Problems

    Due to errors in the feature branch or changes in the ``master``
    branch, after merging the feature branch into the ``master``
    branch unit errors may occur.

  This kind of job **should** basically perform the following steps

  #. Detect changes in branches named
     :samp:`feature-{NAME-OR-ISSUE-NUMBER}` or :samp:`bug-{ISSUE-NUMBER}`
     (see :ref:`git-branch-names`)
  #. Merge the feature branch in question into the ``master`` branch
     (automated by the `git`_ plugin for Jenkins)
  #. Build the resulting source tree (using the same build recipe as
     the :samp:`{NAME}-trunk` branch)
  #. Run unit tests in the resulting source tree (likewise)

  This kind of job **should not** perform the following steps:

  * Record a history of any kind of metrics (since feature branches
    are transient and builds of different feature branches will be
    mixed arbitrarily)
  * Trigger builds of downstream projects (this reduces load on the CI
    server and prevents the job from blocked for subsequent builds
    resulting in quicker turnarounds)
  * Build and upload packages
  * Send emails
  * Participate in the continuous integration game

:samp:`{NAME}-trunk-package`

  TODO

:samp:`{NAME}-{VERSION}`

  TODO

:samp:`{NAME}-{VERSION}-package`

  TODO

Example
-------

The figure shows jobs for the ``trunk`` and ``0.7`` versions of a
project called ``rsb-cpp``.

.. image:: /_static/rsb-cpp-jobs.png

In this example, ``-static-analysis`` jobs have been added to perform
time-consuming operations in a dedicated job.

Furthermore, there are Windows-specific jobs (``-windows`` suffix)
which use different build recipes. Ideally, this would not be
necessary, but there is currently no realistic perspective of having
build recipes which are portable across UNIX and Windows.

Setting up Jobs
===============

TODO