The project recipe
******************

The ``collective.buildbot:project`` recipe is responsible for creating
the buildbot configuration for a project which is a single testable
component. Whether this project corresponds to a single sofware
package or many is up to you. In most cases a project corresponds to a
buildout which in turn may contain one or many software packages. Each
project has a separate state and is visualized as a column in the
waterfall display.

This recipe should be used in the same buildout with
``collective.buildbot:master``.


Supported options
=================

The recipe supports the following options:

``slave-names`` (mandatory)

  A white-space separated list of slave names that the project will be
  built on. These must correspond to the section names that use the
  ``collective.buildbot:slave`` recipe and that are consequently
  referred in the ``slaves`` option of the section using the
  ``collective.buildbot:master`` recipe.

``vcs`` (optional)

  The version control system used to obtain the source code for the
  project. Defaults to ``svn``. Other possible values are: ``hg``,
  ``bzr`` and ``git``.

``repository`` (mandatory)

  The URL to the code repository that corresponds to the selected
  version control system. For Subversion this could be something like
  ``https://svn.plone.org/svn/collective/collective.buildbot/trunk``
  or for Git something like
  ``git@github.com:dokai/hexagonit-swfheader.git``.

``branch`` (optional)

  The branch in the version control system that will be checked
  out. For Subversion checkouts you should provide the full URL to the
  desired branch (e.g. something that ends with ``trunk`` or
  ``branches/foo``) and leave this option empty. For Git repositories
  the default value is ``master``.

``email-notification-sender`` (optional)

  An email address that will be used in the From: header for the
  notification messages.

``email-notification-recipients`` (optional)

  A newline separated sequence of email addresses the notification
  messages will be sent to.

``build-sequence`` (optional)

  A newline separated sequence of shell commands executed on the build
  slave after checking out the code from the repository that will
  build the project.

  Defaults to::

    bin/python bootstrap.py
    bin/buildout

  which is appropriate for buildout based projects.

``test-sequence`` (optional)

  A newline separated sequence of shell commands executed on the build
  slave to execute the test suite. Defaults to::

    bin/test

``periodic-scheduler`` (optional)

  Sets up a periodic scheduler that schedules a build every ``n``
  minutes, where ``n`` is the given integer value.

``cron-scheduler`` (optional)

  Sets up a cron-like scheduler that schedules a build at a given
  time. The time is configured in a crontab manner using white space
  separated values for the following fields::

    [minute] [hour] [day of month] [month] [day of week]

  The values should be integers in the approriate range for the given
  field or ``*`` (asterisk) for all values. For example to schedule a
  build at 3:00 am every night you would use::

    cron-scheduler = 0 3 * * *
   

Example usage
=============

We'll start by creating a buildout that uses the recipe. A full
example would propably have other sections defining the build master
and slaves, but here we will demonstrate only the use of the
``collective.buildbot:project`` recipe.

    >>> write('buildout.cfg',
    ... """
    ... [buildout]
    ... parts = my.package
    ... 
    ... [my.package]
    ... recipe = collective.buildbot:project
    ... slave-names = slave1
    ... vcs = svn
    ... repository = http://example.com/svn/my.package/trunk
    ... """)

Running the buildout gives us::

    >>> print system(buildout)
    Installing my.package.
    Generated config '/sample-buildout/parts/projects/my.package.cfg'.

As we can see, the recipe generated the project configuration file
under the ``projects`` directory in the parts::

    >>> cat(join('parts', 'projects', 'my.package.cfg'))
    [project]
    ...
    name = my.package
    repository = http://example.com/svn/my.package/trunk
    ...
    slave-names = slave1
    ...
    vcs = svn
    <BLANKLINE>

The projects recipe
*******************

The ``collective.buildbot:projects`` recipe is deprecated and not
supported anymore.

  
