Goatlog concepts
################

Goatlog provides a format to report information about the execution of tasks, along
with information about the context of the tasks during the execution.

What is called "Execution" here is also called build in Buildbot and Jenkings. We
prefer to not call it so as it involves much more than just building things.

An execution contains three main things:

 * Target: What is being tested?

 * Environment: Data about the environment of this execution. It can contain the Operating
   System, as well with other information about the environement the execution
   is being run onto.

 * Execution-content: Report on the execution.

**Target** and **Environment** are loosly defined and usually context specific.

Execution-content
=================

The execution-content is structured as a tree: Contexts are opened and content
is added into this specific context.

Context node
=============

The context node is a way to provide information about which part of the 
execution produced some content. The most frequent context is a `Step` context, 
which represents a step (an action) in the execution flow.

A FileTestContext, representing a test file could also be used as a specilized
context node for instance.

Context nodes can be embedded into other context nodes.

Here is the format of a context node:

:type:

    The type of context. This might impact the kind of element allowed in the
    context.

    string in a valid subset

:id:

    The identifier of the context, should be unique.

    string

:status:

    The status of the context. One of the following:

    * missing
    * skipped
    * killed
    * error
    * failure
    * nodata
    * partial
    * success

:start date:

    When the context was open (if applicable).

:end date:

    When the context was close (if applicable).

Step context
------------

A context representing a step. Classically, first records will be arguments given to the step and the last one are content produced by step (stout, stderr or more precise data).

TODO: Following contexts requires more work.

File context
------------

The file context

:file path:

    path of the file (relative ?)

Test Group
----------

    * Name

Leaf node
=========

The Leaf Node is the normal way of report informations.

LogMessage
----------

The log message is the most common leaf node, normal "logging" api will produce some LogRecord. It contain:

 * severity

 * message

 * category (optionnal)

 * line (in File context)

Version Info
------------

The version info is a leaf node used for giving informations about various components version. It contains:

 * name

 * version

Config Info
-----------

The config info is a leaf node used for report configuration passed to the execution. It contains:

 * Variable

 * Value

.. note:

    Version-info are generic triplet data: "type", "name", "value"


Test 
----

The test record represents a test case, it's format is:

:name:

    The test name

:result: 

    Result of the test:

    * success
    * failure
    * skipped
    * error
    * unexpected-success


:message:

    Message associated to the test (if applicable).

:traceback:

    Traceback of a possible exception (if applicable).