The @PLUGIN@ plugin seperates test results from comments.  It provides a
separate channel for Gerrit to store test metadata and view them on the
Gerrit UI.  The metadata can be stored in the Gerrit database or in a
completely separate datastore.

Typically a CI system, like [Jenkins], will post test metadata to Gerrit as a
comment.  It looks something like this..

```
Jenkins                     Aug 24 3:57 PM
Patch Set 5: Verified-1
Build Failed
http://jenkins.acme.com/job/python-27-wacko/4/ : FAILURE
http://jenkins.acme.com/job/python-27-pep8/6/ : SUCCESS
http://jenkins.acme.com/job/python-27/4/ : SUCCESS
..
```

The problem occurs when there are many jobs verifying each patchset.  An
increased number of reports from Jenkins can overwhelm reviewers who must look
through the comments and decipher which replies to pay attention to.  After a
while the CI reports become more like spam.  Usually human reviewers only
want to view comments that have been posted by other humans reviewers not bots.
Since humans and bots must share a communications (or comments) channel it's
difficult to separate the two competing pieces of data for the purposes of
reviewing, visualizations and even analytics.

This is where the @PLUGIN@ plugin comes in.  It creates a separate channel for
bots to report info to Gerrit.  It provides a separate database to store the
info and it provides a set of SSH commands and REST endpoints to save
and retrieve the data.  It also provides UI components to view the data
outside of the Gerrit comments.

### <a id="workflow"></a>
### `Workflow`

Any CI system can be used with the @PLUGIN@ plugin.

A typical workflow:
1. CI system triggers on a new patchset, ref update or comment.
2. CI system executes build jobs.
3. CI system reports test results with the @PLUGIN@
[ssh command](cmd-save.md) or [rest-api](rest-api-changes.md).
4. CI system reports a combined `Verified` vote based on the results of each job
using the [review ssh command](../../../Documentation/cmd-review.html) or
[review rest api](../../../Documentation/rest-api-changes.html#set-review).
5. Users can view per patch job results on Gerrit UI or retrieve the results
using the @PLUGIN@ rest api.

_NOTE_: The Jenkins [Gerrit verify status reporter plugin] documentation
contains specific instructions on setting up this workflow with the
Jenkins CI system.


### <a id="change-screen"></a>
### `Change Screen`
Visualized based on the [job results](#job-results) info

![PreferencesScreenshot](images/job_results.png)


### <a id="job-results"></a>
### `Job Results`

The job score (or value) is the result from the executed build.  This
score is independent of the Gerrit label (i.e. `Verified`) score. The
reporter scores each build job and then (if given permission) scores the
combined Verified vote.

|Score          |Result  |
|:------------- |:-------|
|less than 0    |Failed  |
|0              |Unstable|
|1              |Passed  |
|2              |In-progress if enableInProgressStatus=true, otherwise Passed|
|greater than 2 |Passed  |


The information icon is an indicator that a job has abstained from voting
(or is a non-voting job).  Abstaining typically indicates that a job's
score may not factor into determining the combined vote.

If enableInProgressStatus is true then the loading icon is an indicator that a job
has been set with value 2 and identified as 'in progress'.
_NOTE_: The Jenkins [Gerrit verify status reporter plugin] currently doesn't
support in-progress or any equivalent status so enabling progress status makes
sense only if one uses own postbuild/prebuild custom pipeline logic for setting
statuses via API. For instance:
1. In-progress status with value=2 is sent via API as the first step of the build.
2. From postbuild section actual finish status is calculated in groovy script and
is send via API.


### <a id="configure-panels"> @PLUGIN@ configure-panels

Configuration
-------------

The @PLUGIN@ job panels can be configured in the [gerrit.config]
(../../../Documentation/config-gerrit.html#_file_code_etc_gerrit_config_code)
file.

#### Parameters

|Field Name                    |Description|
|:-----------------------------|:----------|
|showJobsPanel                 | Whether jobs panel should be displayed (default to true)|
|showJobsDropDownPanel         | Whether jobs drop down panel should be displayed (default to true)|
|showJobsSummaryPanel          | Whether jobs summary panel should be displayed (default to true)|
|showJobsBelowRelatedInfoBlock | Whether jobs panel should be positioned below related info block (default to false)|
|enableInProgressStatus        | Whether value=2 should be treated as 'in progress' status (default to false)|
|sortJobsPanel                 | The order of jobs sorting on jobs panel (REPORTER,NAME,DATE default to REPORTER). Both upper and lower cases are allowed.|
|sortJobsDropDownPanel         | The order of jobs sorting on jobs drop down panel (REPORTER,NAME,DATE default to REPORTER). Both upper and lower cases are allowed.|


#### Example

```
[plugin "@PLUGIN@"]
   showJobsDropDownPanel = false
```


[Jenkins]: https://jenkins.io
[Gerrit verify status reporter plugin]: https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Verify+Status+Reporter+Plugin