==============
ReleaseBuilder
==============

Introduction
============
ReleaseBuilder is for building releases.  How very exciting.

Background
==========

Because building releases MUST be automated in order to make certain that they
are consistent acros environmnets, that they are complete without requiring
intervention to make them functional, and that they can simply and easily be
constructed, taking a minimum of user-input to generate, it is necessary to
have a set of repeatable logic to do that building.

Usage
=====

  >>> from releasemanager.builder import ReleaseBuilder
  >>> rb = ReleaseBuilder("release_builder_template")
  >>> rb.build(trunk=True)
  True
  >>>                                                                           

In the ReleaseManager heirarchy, the relevant Builder code is contained, as
you might expect, in releasemanager/builder.  To use the library, it is as
simple as importing ReleaseBuilder from the builder module, and 
instantiating it with the name of a config, and the path to that config.

This, however, is where the real work comes in.

The base.py under builder provides the class from which you must inherit in 
when building new BuildBehaviors.  BuildBehaviors are the core of the RB 
functionality.  In effect, all ReleaseBuilder instances instantiate a class
(based on configs and runtime-loading, not directly) that implements a
__call__ method that the ReleaseBuilder will defer to as it's .build() method.

The primary methods provided by the base BuildBehavior are:
  clean()
    - simply cleans the builder's working directory
  checkout()
    - exports a copy of a project's source from svn based on branch, revision, or url
  setLogger()
    - set's the logger for the object so that it will log correctly
  fullBuild()
    - performs a clean, a checkout, and then runs an object's runLocalBuild

It also provides, but requires that a subclass override, a runLocalBuild method.
The runLocalBuild method is the method that any BuildBehavior subclass must
override in order to have it's own unique behavior take effect.  

Configuration
=============

In the conf directory there is a builder directory holding all builder config
files.  Builder conf files require the following structure:

<build_behavior 
    name="template"
    klass="TemplateBuildBehavior"
    package="releasemanager.builder.template"
    >
  <svn_user>username</svn_user>
  <svn_pass>password</svn_pass>
  <svn_url>http://svn.fakehost.fake/repo</svn_url>
  <svn_target>template</svn_target>
  <svn_work_dir>some_working_directory</svn_work_dir>
  <ignore_clean_error>bool</ignore_clean_error>
  <archive_output>some_archive_output_directory</archive_output>
  <logging_path>logging_path_output</logging_path>
  <logging_level>DEBUG</logging_level>
  <!-- all subclass relevan configs here -->
</build_behavior>

Fairly self explanatory, but just to reiterate:
  - name: name of the build behavior
  - klass: the class of the build behavior to be used
  - package: where to load the class from
  - svn_user: username to use for the subversion checkout.  must have at least read access.
  - svn_pass: password for subversion.
  - svn_url: url of the repository
  - svn_target: the target to which to check out the svn code
  - svn_work_dir: working directory to use 
  - archive_output: where the archives produced by a build set should go
  - logging_path: where the logs for the build should be put
  - logging_level: the severity of log messages we want to see