gerrit-buildbot-plugin: A C++ repository from davido

Buildbot Gerrit Plugin
======================

Buildbot Gerrit Plugin (BGP) is a multi project and multi platform queue manager
for patch verification.

It coordinates the decentral located tinderboxes without having a continued
network connection to them by maintaining project and platform specific working
queue of tasks for each gerrit patch. A patch set considered to be verified
if and only if all tinderbox tasks are reported success back.
In this case `verified` status is reported back to gerrit.
In addition log publication is provided by delegating the log to jenkins
instance.

Workflow
--------

1. During BGP activation the configuration file buildbot.config is read and
   gerrit-stream event listener is installed.
   Depending on trigger strategie for specific project, build is triggered.
2. tinderbox that configured gerrit verification
   (see tb' script) periodically calls BGP `get` ssh command and pick gerrit
   patch for verification. Note that because of blocking
   queue only one tinderbox per gerrit patch and per platform get engaged.
   When a tinderbox assigned a test build this event is repported as a review
   message.
3. tinderbox build the recieved gerrit task and report the outcome and the
   the log file with BGP `put` ssh command. When a tinderbox outcome is known,
   report that in a review message (success, failed, cancelled).
   If --state=canceled is reported, then the task is rescheduled again in the 
   build queue.
4. Once all tasks for a job are ready, the combined verify result is reported
   back to gerrit.

Aditional features
==================

Discarding pending tasks
------------------------

Once one platform reports failure, all pending tasks for other platforms are
discarded from the queue.

Handling stale patch sets
-------------------------

When during patch verification a new patch set is submittedto gerrit, then all
pending tasks are discarded, and the running tasks only report single status
to gerrit, no combined status is set in that case.


Forge reviewer Identity
-----------------------

Per default a review is reported back to gerrit with Buildbot's own identity,
i. e. so called "forge reviewer identity" feature is activated per default.
It can be overriden (setting configure option `user.forgeReviewerIdentity`
to `false`) to report a review with caller's own identity.

Mutliple branches support
-------------------------

Multiple branches per project are supported. A branch must be configured in
`project.NAME.branch` to be considered for bulld scheduling.

Skipping pending build task (not implemented)
---------------------------

With per project and per branch options `project.PROJECT_NAME.branch.BRANCH_NAME.policy`
`soft` or `strict` outcome reporting policy can be configured. If 
`project.PROJECT_NAME.branch.BRANCH_NAME.policy` is set to `soft` then
build is skipped for pending tasks in the platform specific queue once result
for one (or more) build task(s) is reported. With the option 
`project.PROJECT_NAME.branch.BRANCH_NAME.skipThreshold` the min. number of reported
result can be configured. Default is 1.

Example: build for platform `MAC` is ready and the result is reported by a `put` command.
The build on `Linux` platform is still runnning, and the `Windows` platform is pending.
Now the `Linux` platform is ready and is reported by `put` command: if the `Windows` task
is still pending, then it is skipped: the task is dropped from the `Windows` queue and
the combined status `+1` is reported back to gerrit.

Idle timeout (not implemented)
------------------------------
If task is not picked up for building within defined time, the task for this platform is
cancelled.

Engaged timeout (not implemented)
---------------------------------
If task is not get reported within defined time, the task is moved again in init state,
and can be picked up again for building. If the original tb reports the status after it,
then it is discarded.

Contribution:
=============
Pull requests are wellcomed.
davido/gerrit-buildbot-plugin
