Setup and plugin user guide
Explains:
* what it is
* what it does
* how to set it up
* how to use it
* info about development
Feature: Issue 9922
Change-Id: I796c95e61f6d74f181f3c2187c09f9e9d3e59745
diff --git a/README.md b/README.md
index 497b201..017aad4 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,77 @@
-# analytics-wizard
-Wizard to provision a new GerritAnalytics stack
+# Analytics Wizard plugin
+
+Wizard to locally setup an Analytics Dashboard like the [Gerrit's one](https://gerrit-analytics.gerritforge.com).
+This will allow you to explore the potentials of **DevOps Analytics** on your own repositories.
+
+## What it DOES
+* Setup a ready to use Analytics Dashboard with some defaults charts
+* Populate the Dashboard with data coming from the repos you would like to analyse
+
+## What it DOES NOT
+* Schedule recurring import of the data, but just the first one
+* Create a production ready environment. It is meant to build a *playground* to explore the potential of **DevOps
+analytics**
+* Create multiple dashboards
# Setup
-this plugin is being developed against gerrit master (2.16), thus it relies on `gerrit-plugin-api-2.16-SNAPSHOT`
+## Prerequisites
+* Gerrit v2.16
+* [Analytics plugin](https://gerrit.googlesource.com/plugins/analytics/)
-In order to make `gerrit-plugin-api-2.16-SNAPSHOT` available locally you can run the following from a gerrit checkout dir:
+##Installation
+Copy the [latest available jar](https://gerrit-ci.gerritforge.com/job/plugin-analytics-wizard-sbt-master-master/) into the Gerrit plugins directory and restart it.
+Assuming `/usr/local/gerrit ` is the location of your Gerrit installation simply execute the following:
+
+```bash
+curl -o /tmp/analytics-wizard.jar https://gerrit-ci.gerritforge.com/job/plugin-analytics-wizard-sbt-master-master/analytics-wizard.jar &&\
+cp /tmp/analytics-wizard.jar /usr/local/gerrit/plugins
```
-./tools/maven/api.sh install
-```
\ No newline at end of file
+
+# How to use it
+Once the plugin is installed and you are logged in Gerrit browse to this url: [https://<you_gerrit_url>/plugins/analytics-wizard/static/analytics-dashboard.html]()
+
+You will land on this screen:
+
+
+
+Different parameters can be configured:
+* **Dashboard name** (required): name of the dashboard you are about to create
+* **Projects prefix** (optional): prefix of the projects you want to import, i.e.: to import all the projects under the Gerrit namespace, you can specify `gerrit/`. *Note: It is not a regular expression.*
+* **Aggregation type** (required): the data can be aggregated by `email only`, by `email per hour`, by `email per day`, by `email per month` or by `email per year`.
+* **Date time-frame** (optional): time window you want to collect data about
+* **Username/Password** (optional): credentials for Gerrit API, if basic auth is needed
+
+Once you set the parameters pressing the "Create Dashboard" button will trigger the Dashboard creation and the data import.
+
+*Beware this operation will take a while since it requires to download several Docker images and run an ETL job to collect and aggregate the data.*
+
+At the end of this operation you will be presented with a dashbaord similar to this one:
+
+
+
+You can now navigate among the different charts and uncover the potentials of DevOps analytics!
+
+# Components interaction
+
+
+
+# Development
+
+* [Project Git repo](https://gerrit.googlesource.com/plugins/analytics-wizard/)
+* The project relies on:
+ * an [ETL data extractor](https://gerrit.googlesource.com/apps/analytics-etl)
+ * an [Analytics plugin](https://gerrit.googlesource.com/plugins/analytics/) to expose Gerrit metrics
+* [CI/CD](https://gerrit-ci.gerritforge.com/job/plugin-analytics-wizard-sbt-master-master/)
+
+To build the plugin, [JDK 1.8](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) and [sbt](https://www.scala-sbt.org/) are required.
+Once installed use *sbt* to build:
+```bash
+cd ./analytics-wizard
+sbt assembly
+```
+
+This will compile, test and package the plugin artifact, which can be found in `./target/scala-2.11/analytics-wizard.jar`.
+
+
diff --git a/resources/dashboard.png b/resources/dashboard.png
new file mode 100644
index 0000000..3d44090
--- /dev/null
+++ b/resources/dashboard.png
Binary files differ
diff --git a/resources/sequence.png b/resources/sequence.png
new file mode 100644
index 0000000..a316f11
--- /dev/null
+++ b/resources/sequence.png
Binary files differ
diff --git a/resources/sequence.puml b/resources/sequence.puml
new file mode 100644
index 0000000..9a468a1
--- /dev/null
+++ b/resources/sequence.puml
@@ -0,0 +1,34 @@
+@startuml
+
+actor User
+box "Gerrit installation" #LightYellow
+ participant WizardPlugin
+ participant AnalyticsPlugin
+end box
+box "Data extraction and visualization"
+ participant ETLJob
+ participant ElasticSearch
+ participant Kibana
+end box
+
+User -> WizardPlugin: CreateDashboard
+WizardPlugin --> User: Ok
+WizardPlugin -> ETLJob: ExtractData
+ETLJob --> WizardPlugin: Ok
+activate ETLJob
+ETLJob -> AnalyticsPlugin: GetCommitsInfo
+activate AnalyticsPlugin
+AnalyticsPlugin -> AnalyticsPlugin: AggreagateData
+AnalyticsPlugin -> ETLJob: CommitsInfo
+deactivate AnalyticsPlugin
+ETLJob -> ETLJob: ProcessCommitsInfo
+ETLJob -> ElasticSearch: StoreCommitsInfo
+deactivate ETLJob
+...
+...
+User -> Kibana: GetDashbaord
+Kibana -> ElasticSearch: GetDataForDashboard
+ElasticSearch -> Kibana: DataForDashboard
+Kibana -> User: Dashboard
+
+@enduml
\ No newline at end of file
diff --git a/resources/wizard.png b/resources/wizard.png
new file mode 100644
index 0000000..3f37b7a
--- /dev/null
+++ b/resources/wizard.png
Binary files differ
