============================================
Buildout recipe managing project deployments
============================================


Overview
========

``bda.recipe.deployment`` offers a deployment cycle and helper scripts for
buildout based projects.


Motivation
==========

While in small projects pinning checkout revisions or package versions in order
to deploy reconstructable setups works fine, the same strategy runs out of
it's possibilities as soon as it comes to deployment of projects where
steps needed to publish a new feature not always follow a consistent and
repeating cycle.

Consider following example. A customer comes up with two feature requests. The
customer always communicates with the project manager, from customer point of
view the cycle is clear. Each feature must be tested and after approving the
rollout could be made. Now the developer imlements feature one, and while the
first feature waits for testing and approval, he wants to implement second one
without influence to the approval cycle.

The deployment cycle consists of three possible installations, further called
environments:

**Development**
    The development environment is used to develop features on developers local
    maschine.

**Release Candidate**
    The environment on the testing maschine accessible for customers testing.

**Live**
    The tested and stable live system.


Process
-------

Overall process:

1) Developer uses ``dev.cfg``. If changes were done
``./bin/deploy candidate MODULENAME NEWVERSION`` is called. Modules RC-branch is
created/synced and the sources section in file for rc environment is modified
and committed.

2) Release Manager uses ``rc.cfg`` on its testing checkout. After svn/git update
and buildout (re-)run the setup contains all release candidates branches.
Software can be tested. In a second cycle Release Manager can merge changes from
development branch into rc branch.

3) Release Manager decides to release a package after testing for live-usage.
In rc-environment ``./bin/deploy release MODULENAME `` is called and the egg is
uploaded to the configured eggserver or saved local. The live-versions section
in file for live-environment is modifed and committed.

4) Live-System-Administrator uses ``live.cfg`` on the live-deployment maschine.
After git/svn up and buildout (re-)run the most recent releases are available.

Optional (if configured) the RC steps 2 and 3  can be omitted and a release may
happen from dev direct to live.

While Developer and Release Candidate needs the add-on ``mr.developer``, Live
does not it.


Buildout Structure
------------------

Proposed buildout structure::

    dev.cfg (manual)
    rc.cfg (manual)
    live.cfg (manual)
    etc/base.cfg (manual)
    etc/deployment.cfg (manual)
    etc/sources-dev.cfg (manual)
    etc/sources-rc.cfg (generated)
    etc/versions-rc.cfg (generated)
    etc/versions-live.cfg (generated)
    cfg/versions-global.cfg (manual, optional)

**dev.cfg**
    Contains parts for local development, includes developer tools if
    necessary. Included parts:
    
        - ``base.cfg``
        - ``versions-global.cfg``
        - ``sources-dev.cfg``
        - ``deployment.cfg``

**rc.cfg**
    Contains parts for local on a test-server. Included parts:
    
        - ``base.cfg``
        - ``versions-global.cfg``
        - ``versions-rc.cfg``
        - ``sources-rc.cfg``
        - ``deployment.cfg``

**live.cfg**
    Contains parts for deployment on a live-server. Included parts:
    
        - ``base.cfg``
        - ``versions-global.cfg``
        - ``versions-live.cfg``

**base.cfg**
    contains all common sections and settingsof the buildout needed by all
    three types of environment.

**deployment.cfg**
    Contains deployment specific sections and settings, such as parameters for
    deployment and list of managed packages and which dist-server to use.

**global-versions.cfg**
    Contains the common version section. In smaller projects this can be put in
    base.cfg

**sources-dev.cfg**
    Contains the sources-section for all developer controlled sources.

**sources-rc.cfg**
    Contains the sources for Release-Candidate setup. This file is generated by
    scripts. It points to the automatically created branches.

**versions-rc.cfg**
    Contains the versions of developer controlled sources used in
    rc-deployment. This are the packages which do not need a RC step.
    This file is generated by scripts.

**versions-live.cfg**
    Contains the versions of developer controlled sources used in
    live-deployment. This file is generated by scripts.


Commands
--------

In buildouts bin directory there are two main commands which itself have a
bunch of sub commands, the ``deploy`` and the ``bda_deployment_helper``. Latter
is rarely used, i.e. you may need it to fix things. So the main tool for the
daily usage is ``deploy``.

deploy
~~~~~~

Main command for all daily tasks.

Subcommands are context sensitive. In dev environment there are other
commands available than in RC enviroment.

So in ``dev`` environment this are:

**repopasswd**
    sets the username/ password for the pypi server

**info**
    prints info about managed packages.

**version**
    prints version of a package.

**candidate**
    prepare a release candidate for a package, this includes creation of a
    branch.

**release**
    make a release of a package, this includes tagging and upload to the
    index (or local file release) and setting the version in
    ``versions-rc.cfg`` and ``versions-live.cfg``.

In ``rc`` environment the commands are:

**repopasswd**
     see above.

**info**
     see above.

**version**
     see above.

**release**
    make a release of a package, this includes tagging and upload to the
    index (or local file release) and setting the version in
    ``versions-live.cfg``.

**merge**
    merge current trunk/master branch of a package into the rc branch.

All commands and subcommands have a help to find their paramaters.


Source Code
===========

The sources are in a GIT DVCS with its main branches at
`github <http://github.com/bluedynamics/bda.recipe.deployment>`_.

We'd be happy to see many forks and pull-requests to make it even better.


Contributors
============

- Jens W. Klein <jk [at] kleinundpartner [dot] at>

- Robert Niederrreiter <rnix [at] squarewave [dot] at>

