doc: update docs with more info
Update quick start guide with additional info on how to connect
Gerrit and Storyboard servers.
Change-Id: I70fa5afeb273c27941d51d9698687796d1b61d01
diff --git a/src/main/resources/Documentation/about.md b/src/main/resources/Documentation/about.md
index 5c0d532..f47bac2 100644
--- a/src/main/resources/Documentation/about.md
+++ b/src/main/resources/Documentation/about.md
@@ -1,12 +1,12 @@
-This @PLUGIN@ plugin is an [`its-base`][its-base] based plugin that integrates
-Gerrit and [`Storyboard`][storyboard]. The @PLUGIN@ allows users
-to configure how a storyboard story or task should be updated relative
-to Gerrit change updates. For example, it can be configured to
-automatically add comments to a story when a comment is entered to
-an associated Gerrit change. It can also be configured to update a
-story's status upon an update to an associated Gerrit change.
+This @PLUGIN@ plugin is an [`its-base`][its-base] based plugin that
+integrates Gerrit and [`Storyboard`][storyboard]. The @PLUGIN@ plugin
+allows users to configure how a storyboard story and task should be
+updated relative to Gerrit change updates. For example, it can be
+configured to automatically add comments to a story when a comment is
+entered to an associated Gerrit change. It can also be configured to
+update status on a task when an associated Gerrit change is updated.
-For details on how to install this plugin start with the
+For details on how to install and configure this plugin start with the
[Quick Install Guide][quick].
[quick]: quick-install-guide.html
diff --git a/src/main/resources/Documentation/quick-install-guide.md b/src/main/resources/Documentation/quick-install-guide.md
index 132fc10..a2f961c 100644
--- a/src/main/resources/Documentation/quick-install-guide.md
+++ b/src/main/resources/Documentation/quick-install-guide.md
@@ -2,18 +2,19 @@
===================
For general instructions on how to enable and configure an its plugin
-please refer to the general [configuration documentation][config-doc]
+please refer to the general [configuration documentation][config-doc].
Instructions in this document are specific to the @PLUGIN@ plugin.
Install Steps:
-1. Verify Storyboard [REST endpoint][rest-enabled].
-2. [Configure the connection][its-connection].
-3. [Associate a changes with stories][its-associate-change].
-4. [Configure the actions][its-actions] that the plugin will take on a Gerrit change.
-5. [Enable the @PLUGIN@ plugin][its-enable] for the Gerrit project.
+1. [Check Storyboard REST API availability][rest-enabled]
+2. [Connection Configuration][its-connection].
+3. [Verify access to Storyboard][access-enabled]
+4. [Associate Gerrit changes with Storyboard stories and tasks][its-associate-change].
+5. [Configure the actions][its-actions] that the plugin will take on a Gerrit change update.
6. [Install the plugin][its-install]
-7. Restart Gerrit
+7. [Enable the @PLUGIN@ plugin][its-enable] for the Gerrit project.
+8. [Testing][testing]
[rest-enabled]: #rest-enabled
<a name="rest-enabled">Checking REST API availability</a>
@@ -38,9 +39,9 @@
<a name="its-connection">Connection Configuration</a>
-----------------------------------------------------
-In order for @PLUGIN@ to connect to the REST service of your
+In order for the @PLUGIN@ plugin to connect to the REST service of your
Storyboard instance, the url and credentials are required in
-your site's `etc/gerrit.config` or `etc/secure.config` under
+your Gerrit site's `etc/gerrit.config` or `etc/secure.config` under
the `@PLUGIN@` section.
Example:
@@ -51,27 +52,44 @@
password=STORYBOARD_USER_AUTH_TOKEN
```
+[access-enabled]: #access-enabled
+<a name="access-enabled">Check Accessibility</a>
+---------------------------------------------------------
+
+This plugin uses the Storyboard REST endpoints to POST updates. Make sure
+that the STORYBOARD_USER_AUTH_TOKEN has access to update Storyboard stories
+and tasks. To verify this use the [Storyboard story API] from the Gerrit sever
+to post an update. If it fails to update the story you'll need to make the
+necessary changes to allow access between the Gerrit and Storyboard
+servers.
+
+
[its-associate-change]: #its-associate-change
<a name="its-associate-change">Associating Gerrit Changes</a>
-------------------------------------------------------------
-In order for @PLUGIN@ to associate a Gerrit change with
-a Storyboard story, a Gerrit commentlink needs to be
+In order for the @PLUGIN@ plugin to associate a Gerrit change with
+a Storyboard story and task, a Gerrit commentlink needs to be
defined in `etc/gerrit.config`
Example:
```
+[commentlink "story"]
+ match = "\\b[Ss]tory:? #?(\\d+)"
+ link = "http://my_storyboard_instance.com/#!/story/$1"
+ html = ""
[commentLink "@PLUGIN@"]
- match = [Ss][Tt][Oo][Rr][Yy][ ]*([1-9][0-9]*)
- html = "<a href=\"https://my_storyboard_instance.com/#!/story/$1\">story $1</a>"
+ match = "\\b[Tt]ask:? #?(\\d+)"
+ link = "task: $1"
+ html = ""
```
[its-actions]: #its-actions
<a name="its-actions">Configure its actions</a>
-----------------------------------------------
-The @PLUGIN@ plugin can take action when there are updates
+The @PLUGIN@ plugin can take actions when there are updates
to Gerrit changes. Users can define what events will trigger
which actions. To configure this a `etc/its/actions.config`
file is required.
@@ -83,24 +101,39 @@
[rule "update-comment"]
event-type = comment-added
action = add-velocity-comment inline $commenter-name commented on change ${its.formatLink($change-url, $subject)}
+
# add a comment only when a user leaves a -2 or a -1 vote on the Code-Review label on the associated Gerrit change.
[rule "comment-on-negative-vote"]
event-type = comment-added
approval-Code-Review = -2,-1
action = add-comment Boo-hoo, go away!
+
# add a standard comment when there is a status update to the associated Gerrit change.
[rule "comment-on-status-update"]
event-type = patchset-created,change-abandoned,change-restored,change-merged
action = add-standard-comment
-# set task status to 'review' when a patch is uploaded or when a change is restored
-[rule "change_restored"]
+
+# set storyboard task status to 'review' when a patch is uploaded or when a change is restored
+[rule "change-in-progress"]
event-type = patchset-created,change-restored
action = set-status REVIEW
```
+*_NOTE_: A Gerrit restart is required to update these settings.
+
### <a id="task-status"></a>TaskStatus
Valid task status: TODO, REVIEW, INPROGRESS, MERGED, and INVALID
+[its-install]: #its-install
+<a name="its-install">Install the Plugin</a>
+-------------------------------------------------------
+
+In order to install the @PLUGIN@ plugin simply copy the built jar
+file into the `plugins` folder.
+
+[config-common-doc]: config-common.html
+[config-doc]: config.html
+[rules-doc]: config-rulebase-common.html
[its-enable]: #its-enable
<a name="its-enable">Enable the Plugin</a>
@@ -118,18 +151,31 @@
enabled = true
```
-[its-install]: #its-install
-<a name="its-install">Install the Plugin</a>
+[testing]: #testing
+<a name="testing">Testing the Plugin</a>
-------------------------------------------------------
-In order to install the @PLUGIN@ plugin simply copy the built jar
-file into the `plugins` folder.
+Create a new Gerrit change with a commit message that contains a reference
+to the Storyboard story and task.
-[config-common-doc]: config-common.html
-[config-doc]: config.html
-[rules-doc]: config-rulebase-common.html
+Example:
+```
+My change to test integration
+
+This is an example change to test storyboard integration.
+Story: 123
+Task: 1000
+Change-Id: I3912f42c371023eb8bd048a5b17b776801b405e2
+```
+
+Make an update to the Gerrit change (abandone, restore, submit, etc..),
+the @PLUGIN@ plugin should automatically update the corresponding story
+and task in Storyboard.
SEE ALSO
--------
-* More detailed information on actions is found the [rules documentation][rules-doc]
+* More detailed information on actions is found in the [rules documentation][rules-doc]
+
+
+[Storyboard story API]: http://docs.openstack.org/infra/storyboard/webapi/v1.html#put--v1-stories