BOSS Standard Workflow
======================

High Level
^^^^^^^^^^

The BOSS standard workflow is intended to enable automated QA and
improved CI for a product.

It assumes (and helps create) a MeeGo baseline to build against and a
series of 'team' Devel: projects.

Working alongside the OBS 'request' mechanism, BOSS acts as a rapid QA
person.

We'll use the name "Chalk" as a codename for the OBS project holding
locally developed packages. This is also known as a Platform.

BOSS Request Handling in detail
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Objective: A user issues SR to the 'target' project; typically
Product:Trunk. BOSS then evaluates the SR and either actions the SR or
recommends action.

Linking the SRCSRV_REQUEST_CREATE event in a particular project allows
BOSS to handle the SR.

BOSS then carries out a series of steps (only if each previous step succeeds)

 * validates the request by running process, policy, and pre-build tests
 * waits to get a lock on the target project
 * creates a <link> project called ${project}:Testing for testing/simulation
 * (eventually will create a <link> project called ${project}:Testing:$SR for testing/simulation)
 * enables BOSS monitoring on the `boss:*:testing:$SR` project
 * copies package mentioned in the SR to the testing project
 * waits for build in `boss:*:testing:$SR` to complete
 * creates ks
 * builds image from `boss:*:testing:$SR`
 * sends image to OTS
 * accepts SR (optionally notifies RE team to accept SR)
 * releases lock on the target project
 * removes `boss:*:testing:$SR` project

Preparation
^^^^^^^^^^^

The BOSS standard workflow usually uses the following systems:
* OBS
* BOSS
* IMG
* REVS

General
^^^^^^^

Proxies can be a source of trouble. Please check that
/etc/skynet/skynet.env is correctly setup.


OBS
^^^

The OBS needs:
* the boss plugin (zypper in boss-obs-plugin)
* a 'boss' user created via the api. The password will be entered into a config file later.

A baseline repo needs to be available. A MeeGo 1.2.0 repo can be mirrored locally using:

  rsync -avz --delete --exclude images/ rsync://mirrors.kernel.org/mirrors/meego/releases/1.2.0 .

This then needs to be exposed using http (beyond the scope of this document).

The project structure looks like this:
 Chalk:Devel:AREA1  => builds against Chalk:Trunk
 Chalk:Devel:AREA2  => builds against Chalk:Trunk
 Chalk:Devel:AREA3  => builds against Chalk:Trunk
 Chalk:Trunk:Testing  => builds against Chalk:Trunk <link project>
 Chalk:Trunk => builds against MeeGo:XXX

IMG
^^^

IMG should be setup according to its installation guide.

REVS
^^^^

REVS should be setup according to its installation guide.

BOSS
^^^^

The boss system should install boss-standard-workflow-full.
This meta package installs all needed packages (which may be
distributed in a production installation)

Use osc to prepare a working ~/.oscrc that can be used by the -A
paramter to specify an OBS api. This is must be done using an 'admin'
user (and is not the same as the 'boss maintainer' /etc/skynet/oscrc).

Create the project structure by running this command with local values:
  platform_setup -A http://obsapi/ \
  	 --platform Chalk --teams UX,Utils \
	 --repo http://mirror/data/MeeGo/releases/1.2.0/repos/oss/ia32/packages/

Enable BOSS Standard workflow
  enable_swf Chalk:Trunk

Edit the files in /etc/skynet/ to configure them for your local installation.

BOSS Process Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^

When launching a process, BOSS supports JSON formatted configuration of the
process fields. The placement of the configuration is similar to the process 
path:

<process_store>/<path>/<to/<project>/<trigger>.conf

eg.

/srv/BOSS/processes/Project/CE/Trunk/SRCSRV_REQUEST_CREATE.conf

The configuration is formatted as JSON and supports single line 
comments:

  # A comment

  "key": "value"

but NOT:

  "key": "value" # A comment

Testing
^^^^^^^

The default/sample setup works when an SR is sent *to* Chalk:Trunk so
we look in /srv/BOSS/processes/Chalk/Trunk and in that dir is a file
that maps to the SR event that has the process def in it
(SRCSRV_REQUEST_CREATE). In there are lots of process steps calling
participants... those are the ones you want to use 'skynet log'
against

On boss:
  skynet log -n 20 do_build_trial is_repo_published get_build_trial_results change_request_state obsticket

on the img machine we need to track 2 more:
  skynet log -n 20 build_ks build_image


TODO
^^^^
task: an SR accept or revoke should cancel any in-progress build trials.

task: document use of return values and fields in standard workflow


Dependencies
^^^^^^^^^^^^
* robogrator (obs_event)
* standard_workflow
* configure_standard_process
* built_notice (?)
* robogrator_monitor_build_project

obsticket
* obsticket

notify_irc
* notify_irc
notify
* notify
prechecks
* check_process
* check_quality
* check_policy

resolverequest
* prepare_trial_build
* start_trial_build
* change_request_state

IMG
* defineimage
* build_ks
* build_image

OTS
* test_image

??
* getchangelog
* bz
* revs_update