Refactor documentation, so downstream plugins can reuse it easier
Change-Id: I835f37aab0d859dc90410e761111c6fdd3ca8f2b
diff --git a/src/main/resources/Documentation/about.md b/src/main/resources/Documentation/about.md
new file mode 100644
index 0000000..343ec34
--- /dev/null
+++ b/src/main/resources/Documentation/about.md
@@ -0,0 +1,26 @@
+its-base
+========
+
+`its-base` is a common stub for Gerrit plugins that connect to issue
+tracking systems ("ITS"). `its-base` on its own is not meant to be
+installed as plugin to a Gerrit site. Instead `its-base` provides
+common functionality to other plugins, like:
+
+* [its-bugzilla][its-bugzilla]
+* [its-jira][its-jira]
+* [its-rtc][its-rtc]
+
+[its-bugzilla]: https://gerrit-review.googlesource.com/#/admin/projects/plugins/its-bugzilla
+[its-jira]: https://gerrit-review.googlesource.com/#/admin/projects/plugins/its-jira
+[its-rtc]: https://gerrit-review.googlesource.com/#/admin/projects/plugins/its-rtc
+
+`its-base` provides means to:
+
+* Add comments to an ITS (based on a user-defined rules, like "Add a
+ comment to the ITS, if a change references the respective issue").
+* Change status of ITS entries (based on a user-defined rules, like
+ "Set status to `resolved` if a change gets merged that references
+ the respective issue").
+* (De-)activate on per-project base.
+
+<span></span>
diff --git a/src/main/resources/Documentation/build.md b/src/main/resources/Documentation/build.md
index 441519f..c6afec9 100644
--- a/src/main/resources/Documentation/build.md
+++ b/src/main/resources/Documentation/build.md
@@ -54,3 +54,7 @@
How to build the Gerrit Plugin API is described in the [Gerrit
documentation](../../../Documentation/dev-buck.html#_extension_and_plugin_api_jar_files).
+
+[Back to @PLUGIN@ documentation index][index]
+
+[index]: index.html
\ No newline at end of file
diff --git a/src/main/resources/Documentation/config-common.md b/src/main/resources/Documentation/config-common.md
new file mode 100644
index 0000000..6609d8f
--- /dev/null
+++ b/src/main/resources/Documentation/config-common.md
@@ -0,0 +1,184 @@
+Common configuration for `its-base`-based plugins
+=================================================
+
+#### Table of Contents
+* [Identifying ITS ids][identifying-its-ids]
+* [Enabling ITS integration][enabling-its-integration]
+* [Configuring rules of when to take which actions in the ITS][configure-rules]
+* [Legacy configuration][legacy-configuration]
+
+
+
+[identifying-its-ids]: #identifying-its-ids
+<a name="identifying-its-ids">Identifying ITS ids</a>
+-----------------------------------------------------
+
+In order to extract ITS ids from commit messages, @PLUGIN@ uses
+[commentlink][upstream-comment-link-doc]s of name "`@PLUGIN@`".
+
+The first group of `commentlink.@PLUGIN@.match` is considered the
+issue id.
+
+So for example having
+
+```
+[commentLink "@PLUGIN@"]
+ match = [Bb][Uu][Gg][ ]*([1-9][0-9]*)
+ html = "<a href=\"http://my.issure.tracker.example.org/show_bug.cgi?id=$1\">(bug $1)</a>"
+ association = SUGGESTED
+```
+
+in `etc/gerrit.config` would allow to match the issues `4711`, `167`
+from a commit message like
+
+```
+Sample commit message relating to bug 4711, and bug 167.
+```
+
+By setting a `commentlink`'s `association` (see above's example), it
+is possible to require commits to carry ITS references; the following
+values are supported (default is `OPTIONAL`):
+
+MANDATORY
+: One or more issue-ids are required in the git commit message, otherwise
+ the git push will be rejected.
+
+SUGGESTED
+: Whenever the git commit message does not contain one or more issue-ids,
+ a warning message is displayed as a suggestion on the client.
+
+OPTIONAL
+: Bug-ids are liked when found in the git commit message, no warning is
+ displayed otherwise.
+
+
+
+[enabling-its-integration]: #enabling-its-integration
+<a name="enabling-its-integration">Enabling ITS integration</a>
+---------------------------------------------------------------
+
+It can be configured per project whether the issue tracker
+integration is enabled or not. To enable the issue tracker integration
+for a project the project must have the following entry in its
+`project.config` file in the `refs/meta/config` branch:
+
+```
+ [plugin "@PLUGIN@"]
+ enabled = true
+```
+
+If `plugin.@PLUGIN@.enabled` is not specified in the `project.config`
+file the value is inherited from the parent project. If it is not
+set on any parent project the issue integration is disabled for this
+project.
+
+By setting `plugin.@PLUGIN@.enabled` to true in the `project.config`
+of the `All-Projects` project the issue tracker integration can be
+enabled by default for all projects. During the initialization of the
+plugin you are asked if the issue integration should be enabled by
+default for all projects and if yes this setting in the
+`project.config` of the `All-Projects` project is done automatically.
+
+With this it is possible to support integration with multiple
+issue tracker systems on a server. E.g. a project can choose if it
+wants to enable integration with Jira or with Bugzilla.
+
+If child projects must not be allowed to disable the issue tracker
+system integration a project can enforce the issue tracker system
+integration for all child projects by setting
+`plugin.@PLUGIN@.enabled` to `enforced`.
+
+The issue tracker system integration can be limited to specific
+branches by setting `plugin.@PLUGIN@.branch`. The branches may be
+configured using explicit branch names, ref patterns, or regular
+expressions. Multiple branches may be specified.
+
+E.g. to limit the issue tracker system integration to the `master`
+branch and all stable branches the following could be configured:
+
+```
+ [plugin "@PLUGIN@"]
+ enabled = true
+ branch = refs/heads/master
+ branch = ^refs/heads/stable-.*
+```
+
+
+
+[configure-rules]: #configure-rules
+<a name="configure-rules">Configuring rules of when to take which actions in the ITS</a>
+----------------------------------------------------------------------------------------
+
+Setting up which event in Gerrit (E.g.: “Change Merged”, or “User
+‘John Doe’ voted ‘+2’ for ‘Code-Review’ on a change”) should trigger
+which action on the ITS (e.g.: “Set issue's status to ‘Resolved’”) is
+configured through a [rule base][rule-base] in
+`etc/its/action.config`.
+
+[rule-base]: config-rulebase-common.html
+
+
+
+[legacy-configuration]: #legacy-configuration
+<a name="legacy-configuration">Legacy configuration</a>
+-------------------------------------------------------
+
+In this section we present the legacy configuration that uses
+`etc/gerrit.config` directly. As this legacy part will be removed at
+some point, please upgrade to the rule [rule based
+approach][rule-base].
+
+The following configuration settings are available:
+
+`@PLUGIN@.commentOnChangeAbandoned`
+: If true, abandoning a change adds an ITS comment to the change's
+ associated issue.
+
+ Default is `true`.
+
+`@PLUGIN@.commentOnChangeCreated`
+: If true, creating a change adds an ITS comment to the change's
+ associated issue.
+
+ Default is `false`.
+
+`@PLUGIN@.commentOnChangeMerged`
+: If true, merging a change's patch set adds an ITS comment to
+ the change's associated issue.
+
+ Default is `true`.
+
+`@PLUGIN@.commentOnChangeRestored`
+: If true, restoring an abandoned change adds an ITS comment to
+ the change's associated issue.
+
+ Default is `true`.
+
+`@PLUGIN@.commentOnCommentAdded`
+: If true, adding a comment and/or review to a change in Gerrit
+ adds an ITS comment to the change's associated issue.
+
+ Default is `true`.
+
+`@PLUGIN@.commentOnFirstLinkedPatchSetCreated`
+: If true, creating a patch set for a change adds an ITS comment
+ to the change's associated issue, if the issue has not been
+ mentioned in previous patch sets of the same change.
+
+ Default is `false`.
+
+`@PLUGIN@.commentOnPatchSetCreated`
+: If true, creating a patch set for a change adds an ITS comment
+ to the change's associated issue.
+
+ Default is `true`.
+
+`@PLUGIN@.commentOnRefUpdatedGitWeb`
+: If true, updating a ref adds a GitWeb link to the associated
+ issue.
+
+ Default is `true`.
+
+[Back to @PLUGIN@ documentation index][index]
+
+[index]: index.html
\ No newline at end of file
diff --git a/src/main/resources/Documentation/config-connectivity.md b/src/main/resources/Documentation/config-connectivity.md
new file mode 100644
index 0000000..0731c94
--- /dev/null
+++ b/src/main/resources/Documentation/config-connectivity.md
@@ -0,0 +1,16 @@
+Configuring connectivity for @PLUGIN@
+=====================================
+
+```
+THIS FILE IS A PLACEHOLDER.
+
+PLEASE GET THE @PLUGIN@ MAINTAINER TO DOCUMENT WHAT SETTINGS ARE
+NEEDED.
+
+UNTIL THEN, PLEASE CHECK @PLUGIN@'s SOURCE CODE ON HOW TO SET UP
+CONNECTIVITY.
+```
+
+[Back to @PLUGIN@ documentation index][index]
+
+[index]: index.html
\ No newline at end of file
diff --git a/src/main/resources/Documentation/config-rulebase-common.md b/src/main/resources/Documentation/config-rulebase-common.md
new file mode 100644
index 0000000..59a12bd
--- /dev/null
+++ b/src/main/resources/Documentation/config-rulebase-common.md
@@ -0,0 +1,594 @@
+Rule base configuration
+=======================
+
+#### Table of Contents
+* [Overview][overview]
+* [Rules][rules]
+* [Conditions][conditions]
+* [Event Properties][event-properties]
+* [Actions][actions]
+
+[overview]: #overview
+<a name="overview">Overview</a>
+-------------------------------
+
+In this part we describe how to specify which events in Gerrit (E.g.:
+“Change Merged”, or “User ‘John Doe’ voted ‘+2’ for ‘Code-Review’ on a
+change”) trigger which actions (e.g.: “Set issue's status to
+‘Resolved’”) on the ITS.
+
+Actions on the ITS and conditions for the action to take place are
+configured through the rule base in `etc/its/actions.config` in the
+site directory. The rule base is a git config file, and may contain an
+arbitrary number of rules. Each rule can have an arbitrary number of
+conditions and actions. A rule fires all associated actions, once all
+of its conditions are met.
+
+A simple `etc/its/actions.config` may look like
+
+```
+[rule "rule1"]
+ event-type = change-merged
+ action = add-standard-comment
+[rule "rule2"]
+ event-type = comment-added
+ approval-Code-Review = -2,-1
+ action = add-comment Oh my Goodness! Someone gave a negative code review in Gerrit on an associated change.
+```
+
+This snippet defines two rules (`rule1`, and `rule2`). On merging a
+change that's associated to some issues, `rule1` adds a predefined
+standard comment for “Change Merged” to each such issue. If someone
+adds a comment to a change that is associated to some issues and votes
+“-2”, or “-1” for “Code-Review”, `rule2` adds the comment “Oh my
+Goodness! Someone gave a negative code review in Gerrit on an
+associated change.” to each such issue.
+
+The order of rules in `etc/its/action.config` need not be
+respected. So in the above example, do not rely on `rule1` being
+evaluated before `rule2`.
+
+[rules]: #rules
+<a name="rules">Rules</a>
+-------------------------
+
+Each rule consists of three items: A name, a set of conditions, and a
+set of actions.
+
+The rule's name (`rule1`, and `rule2` in the above example) is
+currently not used and only provided for convenience.
+
+For each rule the option `action` is interpreted as action. Any other
+option of a rule is considered a condition.
+
+Each of a rule's actions is taken for events that meet all of a
+rule's conditions. If a rule contains more than one action
+specifications, the order in which they are given need not be
+respected.
+
+There is no upper limit on the number of elements in a rules set of
+conditions, and set of actions. Each of those sets may be empty.
+
+[conditions]: #conditions
+<a name="conditions">Conditions</a>
+-----------------------------------
+
+The conditions are lines of the form
+
+```
+ name = value1, value2, ..., valueN
+```
+
+and match (if 'value1' is not `!`), if the event comes with a property
+'name' having 'value1', or 'value2', or ..., or 'valueN'. So for
+example to match events that come with an `association` property
+having `subject`, or `footer-Bug`, the following condition can be
+used:
+
+```
+ association = subject,footer-Bug
+```
+
+If 'value1' is `!`, the conditon matches if the event does not come
+with a property 'name' having 'value2', or ..., or 'valueN'. So for
+example to match events that do not come with a `status` property
+having `DRAFT`, the following condition can be used:
+
+```
+ status = !,DRAFT
+```
+
+[event-properties]: #event-properties
+<a name="event-properties">Event Properties</a>
+-----------------------------------------------
+
+The properties exposed by events depend on the kind of event.
+
+For all events, the event's class name is provided in the `event`
+property. Most native Gerrit events provide the `event-type`
+property. So `event-type` (or `event` for other events fired by
+plugins) allows you to write filters that fire only for a certain type
+of event.
+
+The common properties for each event are
+
+`event`
+: The event's class name.
+
+`issue`
+: Issue to which this event is associated. Each event is associated to
+ exactly one issue. If for example an event is fired for a commit
+ message, that would contain more than one issue id (say issue “23”,
+ and issue “47”), then the event is duplicated and sent once for each
+ associated issue (i.e.: once with `issue` being `23`, and once with
+ `issue` being `47`).
+
+`association`
+: How the issue of property `issue` got associated to this event.
+ See [Property: `association`][property-association].
+
+
+The further properties are listed in the event's
+corresponding subsection below:
+
+* [ChangeAbandonedEvent][event-properties-ChangeAbandonedEvent]
+* [ChangeMergedEvent][event-properties-ChangeMergedEvent]
+* [ChangeRestoredEvent][event-properties-ChangeRestoredEvent]
+* [CommentAddedEvent][event-properties-CommentAddedEvent]
+* [DraftPublishedEvent][event-properties-DraftPublishedEvent]
+* [PatchSetCreatedEvent][event-properties-PatchSetCreatedEvent]
+* [RefUpdatedEvent][event-properties-RefUpdatedEvent]
+* [Common properties for events on a change][event-properties-change]
+* [Common properties for events on a patch set][event-properties-patch-set]
+
+[property-association]: #property-association
+### <a name="property-association">Property: `association`</a>
+
+The property `association` describes how the `issue` got associated to
+this event.
+
+An event typically has several `association` properties. Possible
+values are:
+
+`somewhere`
+: issue id occurs somewhere in the commit message of the change/the
+ most recent patch set.
+
+`subject`
+: issue id occurs in the first line of the commit message of the
+ change/the most recent patch set.
+
+`body`
+: issue id occurs after the subject but before the footer of the
+ commit message of the change/the most recent patch set.
+
+`footer`
+: issue id occurs in the last paragraph after the subject of the
+ commit message of the change/the most recent patch set
+
+`footer-<Key>`
+: issue id occurs in the footer of the commit message of the
+ change/the most recent patch set, and is in a line with a key
+ (part before the colon).
+
+ So for example, if the footer would contain a line
+
+ ```
+Fixes-Issue: issue 4711
+```
+
+ then a property `association` with value `footer-Fixes-Issue`
+ would get added to the event for issue “4711”.
+
+`added@<Association-Value>`
+: (only for events that allow to determine the patch set number.
+ So for example, this `association` property is not set for
+ RevUpdatedEvents)
+
+ issue id occurs at `<Association-Value>` in the most recent
+ patch set of the change, and either the event is for patch set
+ 1 or the issue id does not occur at `<Association-Value>` in
+ the previous patch set.
+
+ So for example if issue “4711” occurs in the subject of patch
+ set 3 (the most recent patch set) of a change, but not in
+ patch set 2. When adding a comment to this change, the event
+ for issue “4711” would get a property 'association' with value
+ `added@subject`.
+
+[event-properties-ChangeAbandonedEvent]: #event-properties-ChangeAbandonedEvent
+### <a name="event-properties-ChangeAbandonedEvent">ChangeAbandonedEvent</a>
+
+`abandoner-email`
+: email address of the user abandoning the change.
+
+`abandoner-name`
+: name of the user abandoning the change.
+
+`abandoner-username`
+: username of the user abandoning the change.
+
+`event`
+: `com.google.gerrit.server.events.ChangeAbandonedEvent`
+
+`event-type`
+: `change-abandoned`
+
+`reason`
+: reason why the change has been abandoned.
+
+In addition to the above properties, the event also provides
+properties for the abandoned [Change][event-properties-change], and
+its most recent [Patch Set][event-properties-patch-set].
+
+[event-properties-ChangeMergedEvent]: #event-properties-ChangeMergedEvent
+### <a name="event-properties-ChangeMergedEvent">ChangeMergedEvent</a>
+
+`event`
+: `com.google.gerrit.server.events.ChangeMergedEvent`
+
+`event-type`
+: `change-merged`
+
+`submitter-email`
+: email address of the user causing the merge of the change.
+
+`submitter-name`
+: name of the user causing the merge of the change.
+
+`submitter-username`
+: username of the user causing the merge of the change.
+
+In addition to the above properties, the event also provides
+properties for the merged [Change][event-properties-change], and its
+most recent [Patch Set][event-properties-patch-set].
+
+[event-properties-ChangeRestoredEvent]: #event-properties-ChangeRestoredEvent
+### <a name="event-properties-ChangeRestoredEvent">ChangeRestoredEvent</a>
+
+`event`
+: `com.google.gerrit.server.events.ChangeRestoredEvent`
+
+`event-type`
+: `change-restored`
+
+`reason`
+: reason why the change has been restored.
+
+`restorer-email`
+: email address of the user restoring the change.
+
+`restorer-name`
+: name of the user restoring the change.
+
+`restorer-username`
+: username of the user restoring the change.
+
+In addition to the above properties, the event also provides
+properties for the restored [Change][event-properties-change], and it's
+most recent [Patch Set][event-properties-patch-set].
+
+[event-properties-CommentAddedEvent]: #event-properties-CommentAddedEvent
+### <a name="event-properties-CommentAddedEvent">CommentAddedEvent</a>
+
+NOTE: For consistency with the other events, the `author-...`
+properties of the CommentAddedEvent do not refer to the author of the
+comment, but refer to the author of the change's latest patch set. The
+author of the comment is accessible via the `commenter-...`
+properties.
+
+`commenter-email`
+: email address of the comment's author.
+
+`commenter-name`
+: name of the comment's author.
+
+`commenter-username`
+: username of the comment's author.
+
+`comment`
+: added comment itself.
+
+`event`
+: `com.google.gerrit.server.events.CommentAddedEvent+
+
+`event-type`
+: `comment-added`
+
+For each new or changed approval that has been made for this change, a
+property of key `approval-<LabelName>` and the approval's value as
+value is added. So for example voting “-2” for the approval
+“Code-Review” would add the following property:
+
+`approval-Code-Review`
+: `-2`
+
+In addition to the above properties, the event also provides
+properties for the [Change][event-properties-change] the comment was
+added for, and it's most recent [Patch Set][event-properties-patch-set].
+
+[event-properties-DraftPublishedEvent]: #event-properties-DraftPublishedEvent
+### <a name="event-properties-DraftPublishedEvent">DraftPublishedEvent</a>
+
+`event`
+: `com.google.gerrit.server.events.DraftPublishedEvent`
+
+`event-type`
+: `draft-published`
+
+In addition to the above properties, the event also provides
+properties for the uploaded [Patch Set][event-properties-patch-set],
+and the [Change][event-properties-change] it belongs to.
+
+[event-properties-PatchSetCreatedEvent]: #event-properties-PatchSetCreatedEvent
+### <a name="event-properties-PatchSetCreatedEvent">PatchSetCreatedEvent</a>
+
+`event`
+: `com.google.gerrit.server.events.PatchSetCreatedEvent`
+
+`event-type`
+: `patchset-created`
+
+In addition to the above properties, the event also provides
+properties for the uploaded [Patch Set][event-properties-patch-set],
+and the [Change][event-properties-change] it belongs to.
+
+[event-properties-RefUpdatedEvent]: #event-properties-RefUpdatedEvent
+### <a name="event-properties-RefUpdatedEvent">RefUpdatedEvent</a>
+
+`event`
+: `com.google.gerrit.server.events.RefUpdatedEvent`
+
+`event-type`
+: `ref-updated`
+
+`project`
+: full name of the project from which a ref was updated.
+
+`ref`
+: git ref that has been updated (Typcially the branch, as for example
+ `master`).
+
+`revision`
+: git commit hash the rev is pointing to now.
+
+`revision-old`
+: git commit hash the rev was pointing to before.
+
+`submitter-email`
+: email address of the user that updated the ref.
+
+`submitter-name`
+: name of the user that updated the ref.
+
+`submitter-username`
+: username of the user that updated the ref.
+
+[event-properties-change]: #event-properties-change
+### <a name="event-properties-change">Common properties for events on a change</a>
+
+`branch`
+: name of the branch the change belongs to.
+
+`change-id`
+: Change-Id for the change („I-followed by 40 hex digits” string).
+
+`change-number`
+: number for the change (plain integer).
+
+`change-url`
+: url of the change.
+
+`owner-email`
+: email address of the change's owner.
+
+`owner-name`
+: name of the change's owner.
+
+`owner-username`
+: username of the change's owner.
+
+`project`
+: full name of the project the change belongs to.
+
+`subject`
+: first line of the change's most recent patch set's commit message.
+
+`status`
+: status of the change (`null`, `NEW`, `SUBMITTED`, `DRAFT`, `MERGED`,
+ or `ABANDONED` )
+
+`topic`
+: name of the topic the change belongs to.
+
+[event-properties-patch-set]: #event-properties-patch-set
+### <a name="event-properties-patch-set">Common properties for events on a patch set</a>
+
+`author-email`
+: email address of this patch set's author.
+
+`author-name`
+: name of this patch set's author.
+
+`author-username`
+: username of this patch set's author.
+
+`created-on`
+: Timestamp of creation of the patch set (Seconds since 1st January 1970).
+
+`deletions`
+: number of lines deleted by the patch set.
+
+`insertions`
+: number of lines inserted by the patch set.
+
+`is-draft`
+: 'true', if the patch set is a draft patch set, 'false' otherwise.
+
+`parents`
+: A list of git commit hashes that are parents to the patch set.
+
+`patch-set-number`
+: patch set's number within the change.
+
+`ref`
+: git ref for the patch set (For the 5-th patch set of change 4711, this
+ will be `refs/changes/11/4711/5`).
+
+`revision`
+: git commit hash of the patch set
+
+`uploader-email`
+: email address of the user that uploaded this patch set.
+
+`uploader-name`
+: name of the user that uploaded this patch set.
+
+`uploader-username`
+: username of the user that uploaded this patch set.
+
+[actions]: #actions
+<a name="actions">Actions</a>
+-----------------------------
+
+Lines of the form
+
+```
+ action = name param1 param2 ... paramN
+```
+
+represent the action `name` being called with parameters `param1`,
+`param2`, ... `paramN`.
+
+The following actions are available:
+
+[`add-comment`][action-add-comment]
+: adds the parameters as issue comment
+
+[`add-standard-comment`][action-add-standard-comment]
+: adds a predefined standard comment for certain events
+
+[`add-velocity-comment`][action-add-velocity-comment]
+: adds a rendered Velocity template as issue comment
+
+[`log-event`][action-log-event]
+: appends the event's properties to Gerrit's log
+
+[Further actions][further-actions] may be provided by @PLUGIN@.
+
+[further-actions]: config-rulebase-plugin-actions.md
+
+[action-add-comment]: #action-add-comment
+### <a name="action-add-comment">Action: add-comment</a>
+
+The `add-comment` action adds the given parameters as comment to any
+associated rule.
+
+So for example
+
+```
+ action = add-comment This is a sample command
+```
+
+would add a comment “This is a sample command” to associated issues.
+
+If no parameters are given, no comment gets added.
+
+[action-add-standard-comment]: #action-add-standard-comment
+### <a name="action-add-standard-comment">Action: add-standard-comment</a>
+
+The `add-standard-comment` action adds predefined comments to
+associated issues for change abandoned, merged, restored, and patch
+set created events. For other events, no comment is added to the
+associated issues.
+
+The added comments contain the person responsible for the event
+(abandoner, merger, ...), the change's subject, a reason (if one has
+been given), and a link to the change.
+
+[action-add-comment]: #action-add-comment
+### <a name="action-add-comment">Action: add-comment</a>
+
+[action-add-velocity-comment]: #action-add-velocity-comment
+### <a name="action-add-velocity-comment">Action: add-velocity-comment</a>
+
+The `add-velocity-comment` action renders a Velocity template for the
+event and adds the output as comment to any associated issue.
+
+So for example
+
+```
+ action = add-velocity-comment TemplateName
+```
+
+would render the template `etc/its/templates/TemplateName.vm` add the
+output as comment to associated issues.
+
+If 'TemplateName' is `inline`, the Velocity template to render is not
+loaded from a file, but the template is built by joining the remaining
+parameters. So for example
+
+```
+ action = add-velocity-comment inline Sample template using $subject property.
+```
+
+would render “Sample template using $subject property.” as Velocity
+template.
+
+If 'TemplateName' is not `inline`, further parameters get ignored.
+
+Any [property][event-properties] of the event may be used from
+templates. So for example `$subject` in the above example refers to
+the event's subject property, and `$change-number` would refer to the
+change's number.
+
+Additionally, the context's `its` property provides an object that
+allows to format links using the its' syntax:
+
+`formatLink( url )`
+: Formats a link to a url.
+
+ So for example upon adding a comment to a change, the
+ following rule formats a link to the change:
+
+ ```
+[rule "formatLinkSampleRule"]
+ event-type = comment-added
+ action = add-velocity-comment inline Comment for change $change-number added. See ${its.formatLink($change-url)}
+```
+
+`formatLink( url, caption )`
+: Formats a link to a url using 'caption' to represent the url.
+
+ So for example upon adding a comment to a change, the following rule
+ formats a link to the change using the change number as link
+ capition:
+
+ ```
+[rule "formatLinkSampleRule"]
+ event-type = comment-added
+ action = add-velocity-comment inline Comment for change ${its.formatLink($change-url, $change-number)} added.
+```
+
+[action-log-event]: #action-log-event
+### <a name="action-log-event">Action: log-event</a>
+
+The `log-event` action appends the event's properties to Gerrit's log.
+
+Logging happens at the info level per default, but can be overriden by
+adding the desired log level as parameter. Supported values are
+`error`, `warn`, `info`, and `debug`). So for example
+
+```
+ action = log-event error
+```
+
+appends the event's properties to Gerrit's log at error level. All
+other parameters are ignored.
+
+This action is useful, when testing rules or trying to refine
+conditions on rules, as it make the available properties visible.
+
+[Back to @PLUGIN@ documentation index][index]
+
+[index]: index.html
\ No newline at end of file
diff --git a/src/main/resources/Documentation/config-rulebase-plugin-actions.md b/src/main/resources/Documentation/config-rulebase-plugin-actions.md
new file mode 100644
index 0000000..a0bbb50
--- /dev/null
+++ b/src/main/resources/Documentation/config-rulebase-plugin-actions.md
@@ -0,0 +1,11 @@
+@PLUGIN@-specific actions
+=========================
+
+@PLUGIN@ does not provide further specific actions. Only the [basic
+actions][basic-actions] are available.
+
+[basic-actions]: config-rulebase-common.html#actions
+
+[Back to @PLUGIN@ documentation index][index]
+
+[index]: index.html
\ No newline at end of file
diff --git a/src/main/resources/Documentation/config.md b/src/main/resources/Documentation/config.md
index 81f7660..6830e56 100644
--- a/src/main/resources/Documentation/config.md
+++ b/src/main/resources/Documentation/config.md
@@ -1,641 +1,22 @@
-hooks-its
-=========
+Configuring @PLUGIN@
+====================
-link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/hooks-its['hooks-its']
-is by itself not a real plugin, but the common parent project for issue tracking
-system (ITS) plugins for Gerrit, such as
-link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/hooks-bugzilla['hooks-bugzilla'],
-link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/hooks-jira['hooks-jira']
-or link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/hooks-rtc['hooks-rtc'].
+Configuring @PLUGIN@ is a five step process:
-[[config]]
-Common configuration
---------------------
+1. [Set up the ITS connectivity settings][config-connectivity]
+2. [Set up the general configuration][config-common]
+3. [Set up rule on how/what actions should be taken][config-rulebase-common]
+4. Restart gerrit, so the config changes take effect.
+5. Install the @PLUGIN@ jar in your gerrit site.
-The base functionality for 'hooks-its' based plugins is configured via
-git config files in the site's `etc/its` directory. Footnote:[The
-<<config-legacy,legacy configuration>> directly in `etc/gerrit.config`
-still works, but upgrading to this xref:config[new, more flexible
-approach] is strongly recommended.].
+[config-connectivity]: config-connectivity.html
+[config-common]: config-common.html
+[config-rulebase-common]: config-rulebase-common.html
-Setting up which event in Gerrit (E.g.: “Change Merged”, or “User
-‘John Doe’ voted ‘+2’ for ‘Code-Review’ on a change”) should trigger
-which action on the ITS (e.g.: “Set issue's status to ‘Resolved’”) is
-configured through a xref:config-rule-base[rule base] in
-`etc/its/action.config`.
+Done :-)
-It can be configured per project whether the issue tracker
-integration is enabled or not. To enable the issue tracker integration
-for a project the project must have the following entry in its
-`project.config` file in the `refs/meta/config` branch:
-```
- [plugin "<its-name>"]
- enabled = true
-```
-If `plugin.<its-name>.enabled` is not specified in the `project.config`
-file the value is inherited from the parent project. If it is not
-set on any parent project the issue integration is disabled for this
-project.
+[Back to @PLUGIN@ documentation index][index]
-By setting `plugin.<its-name>.enabled` to true in the `project.config`
-of the `All-Projects` project the issue tracker integration can be
-enabled by default for all projects. During the initialization of the
-plugin you are asked if the issue integration should be enabled by
-default for all projects and if yes this setting in the
-`project.config` of the `All-Projects` project is done automatically.
-
-With this it is possible to support integration with multiple
-issue tracker systems on a server. E.g. a project can choose if it
-wants to enable integration with Jira or with Bugzilla.
-
-If child projects must not be allowed to disable the issue tracker
-system integration a project can enforce the issue tracker system
-integration for all child projects by setting
-`plugin.<its-name>.enabled` to `enforced`.
-
-The issue tracker system integration can be limited to specific
-branches by setting `plugin.<its-name>.branch`. The branches may be
-configured using explicit branch names, ref patterns, or regular
-expressions. Multiple branches may be specified.
-
-E.g. to limit the issue tracker system integration to the `master`
-branch and all stable branches the following could be configured:
-
-```
- [plugin "<its-name>"]
- enabled = true
- branch = refs/heads/master
- branch = ^refs/heads/stable-.*
-```
-
-
-[[config-rule-base]]
-Rule base for Actions
-~~~~~~~~~~~~~~~~~~~~~
-
-In this part we describe how to specify which events in Gerrit (E.g.:
-“Change Merged”, or “User ‘John Doe’ voted ‘+2’ for ‘Code-Review’ on a
-change”) trigger which actions (e.g.: “Set issue's status to
-‘Resolved’”) on the ITS.
-
-Actions on the ITS and conditions for the action to take place are
-configured through the rule base in `etc/its/actions.config` in the
-site directory. The rule base is a git config file, and may contain an
-arbitrary number of rules. Each rule can have an arbitrary number of
-conditions and actions. A rule fires all associated actions, once all
-of its conditions are met.
-
-A simple `etc/its/actions.config` may look like
-----
-[rule "rule1"]
- event-type = change-merged
- action = add-standard-comment
-[rule "rule2"]
- event-type = comment-added
- approval-Code-Review = -2,-1
- action = add-comment Oh my Goodness! Someone gave a negative code review in Gerrit on an associated change.
-----
-
-This snippet defines two rules ('rule1', and 'rule2'). On merging a
-change that's associated to some issues, 'rule1' adds a predefined
-standard comment for “Change Merged” to each such issue. If someone
-adds a comment to a change that is associated to some issues and votes
-“-2”, or “-1” for “Code-Review”, 'rule2' adds the comment “Oh my
-Goodness! Someone gave a negative code review in Gerrit on an
-associated change.” to each such issue.
-
-The order of rules in `etc/its/action.config` need not be
-respected. So in the above example, do not rely on 'rule1' being
-evaluated before 'rule2'.
-
-Rules
-~~~~~
-
-Each rule consists of three items: A name, a set of conditions, and a
-set of actions.
-
-The names of the rules ('rule1', and 'rule2' in the above example) are
-currently not used and only provided for convenience.
-
-For each rule the 'action' parameter is interpreted as action.
-Any other parameter of a rule is considered to be a condition.
-
-Each action of a rule is taken for events that meet all of a rule's
-conditions. If a rule contains more than one action, the order in which
-they are given need not be respected.
-
-There is no upper limit on the number of elements in a rules set of
-conditions, and set of actions. Each of those sets may be empty.
-
-Conditions
-~~~~~~~~~~
-
-The conditions are parameters of the form
-----
-name = value1, value2, ..., valueN
-----
-and (if 'value1' is not +!+) match if the event comes with a property
-'name' having 'value1', or 'value2', or ..., or 'valueN'. So for
-example to match events that come with an 'association' property
-having 'subject', or 'footer-Bug', the following condition can be
-used:
-----
-association = subject,footer-Bug
-----
-
-If 'value1' is +!+, the conditon matches if the event does not come
-with a property 'name' having 'value2', or ..., or 'valueN'. So for
-example to match events that do not come with a 'status' property
-having 'DRAFT', the following condition can be used:
-----
-status = !,DRAFT
-----
-
-[[event-properties]]
-Event Properties
-~~~~~~~~~~~~~~~~
-
-The properties exposed by events depend on the kind of the event.
-
-For all events, the event's class name is provided in the 'event'
-property. Most native Gerrit events provide the 'event-type'
-property. So 'event-type' (or 'event' for other events fired by
-plugins) allows you to write filters that fire only for a certain type
-of event.
-
-The common properties for each event are
-
-'event'::
- The event's class name.
-'issue'::
- Issue to which this event is associated. Each event is associated to
- exactly one issue. If for example an event is fired for a commit
- message that contains more than one issue id (say issue “23”,
- and issue “47"), then the event is duplicated and sent once for each
- associated issue (i.e.: once with 'issue' being +23+, and once with
- 'issue' being +47+).
-'association'::
- How the issue of property 'issue' got associated to this event. An
- event typically has several 'association' properties. Possible
- values are:
- 'somewhere'::: issue id occurs somewhere in the commit message of the
- change/the most recent patch set.
- 'subject'::: issue id occurs in the first line of the commit message
- of the change/the most recent patch set.
- 'body'::: issue id occurs after the subject but before the footer
- of the commit message of the change/the most recent patch set.
- 'footer'::: issue id occurs in the last paragraph after the subject
- of the commit message of the change/the most recent patch set.
- 'footer-<Key>'::: issue id occurs in the footer of the commit
- message of the change/the most recent patch set, and is in a line
- with a key (part before the colon).
- +
- So for example, if the footer would contain a line
-+
-----
-Fixes-Issue: issue 4711
-----
-+
-then a property 'association' with value +footer-Fixes-Issue+ would
-get added to the event for issue “4711”.
-
- 'added@<Association-Value>':::
- (only for events that allow to determine the patch set number. So
- for example, this 'association' property is not set for
- RevUpdatedEvents)
- +
- issue id occurs at '<Association-Value>' in the most recent patch
- set of the change, and either the event is for patch set 1 or the
- issue id does not occur at '<Association-Value>' in the previous
- patch set.
- +
- So for example if issue “4711” occurs in the subject of patch set
- 3 (the most recent patch set) of a change, but not in patch set 2.
- When adding a comment to this change, the event for issue “4711”
- would get a property 'association' with value +added@subject+.
-
-The further properties are listed in the event's
-corresponding subsection below:
-
-* <<event-properties-ChangeAbandonedEvent,ChangeAbandonedEvent>>
-* <<event-properties-ChangeMergedEvent,ChangeMergedEvent>>
-* <<event-properties-ChangeRestoredEvent,ChangeRestoredEvent>>
-* <<event-properties-CommentAddedEvent,CommentAddedEvent>>
-* <<event-properties-DraftPublishedEvent,DraftPublishedEvent>>
-* <<event-properties-PatchSetCreatedEvent,PatchSetCreatedEvent>>
-* <<event-properties-RefUpdatedEvent,RefUpdatedEvent>>
-* <<event-properties-change,Common properties for events on a change>>
-* <<event-properties-patch-set,Common properties for events on a patch set>>
-
-[[event-properties-ChangeAbandonedEvent]]
-ChangeAbandonedEvent
-^^^^^^^^^^^^^^^^^^^^
-
-'abandoner-email'::
- email address of the user abandoning the change.
-'abandoner-name'::
- name of the user abandoning the change.
-'abandoner-username'::
- username of the user abandoning the change.
-'event'::
- +com.google.gerrit.server.events.ChangeAbandonedEvent+
-'event-type'::
- +change-abandoned+
-'reason'::
- reason why the change has been abandoned.
-
-In addition to the above properties, the event also provides
-properties for the abandoned <<event-properties-change,change>>, and
-its most recent <<event-properties-patch-set,patch set>>.
-
-[[event-properties-ChangeMergedEvent]]
-ChangeMergedEvent
-^^^^^^^^^^^^^^^^^
-
-'event'::
- +com.google.gerrit.server.events.ChangeMergedEvent+
-'event-type'::
- +change-merged+
-'submitter-email'::
- email address of the user causing the merge of the change.
-'submitter-name'::
- name of the user causing the merge of the change.
-'submitter-username'::
- username of the user causing the merge of the change.
-
-In addition to the above properties, the event also provides
-properties for the merged <<event-properties-change,change>>, and
-its most recent <<event-properties-patch-set,patch set>>.
-
-[[event-properties-ChangeRestoredEvent]]
-ChangeRestoredEvent
-^^^^^^^^^^^^^^^^^^^
-
-'event'::
- +com.google.gerrit.server.events.ChangeRestoredEvent+
-'event-type'::
- +change-restored+
-'reason'::
- reason why the change has been restored.
-'restorer-email'::
- email address of the user restoring the change.
-'restorer-name'::
- name of the user restoring the change.
-'restorer-username'::
- username of the user restoring the change.
-
-In addition to the above properties, the event also provides
-properties for the restored <<event-properties-change,change>>, and
-its most recent <<event-properties-patch-set,patch set>>.
-
-[[event-properties-CommentAddedEvent]]
-CommentAddedEvent
-^^^^^^^^^^^^^^^^^
-
-NOTE: For consistency with the other events, the 'author-...'
-properties of the CommentAddedEvent do not refer to the author of the
-comment, but refer to the author of the change's latest patch set. The
-author of the comment is accessible via the 'commenter-...'
-properties.
-
-'commenter-email'::
- email address of the comment's author.
-'commenter-name'::
- name of the comment's author.
-'commenter-username'::
- username of the comment's author.
-'comment'::
- added comment itself.
-'event'::
- +com.google.gerrit.server.events.CommentAddedEvent+
-'event-type'::
- +comment-added+
-
-For each new or changed approval that has been made for this change, a
-property of key 'approval-<LabelName>' and the approval's value as
-value is added. So for example voting “-2” for the approval
-“Code-Review” would add the following property:
-
-'approval-Code-Review'::
- +-2+
-
-In addition to the above properties, the event also provides
-properties for the <<event-properties-change,change>> the comment was
-added for, and its most recent <<event-properties-patch-set,patch
-set>>.
-
-[[event-properties-DraftPublishedEvent]]
-DraftPublishedEvent
-^^^^^^^^^^^^^^^^^^^
-
-'event'::
- +com.google.gerrit.server.events.DraftPublishedEvent+
-'event-type'::
- +draft-published+
-
-In addition to the above properties, the event also provides
-properties for the uploaded <<event-properties-patch-set,patch set>>,
-and the <<event-properties-change,change>> it belongs to.
-
-[[event-properties-PatchSetCreatedEvent]]
-PatchSetCreatedEvent
-^^^^^^^^^^^^^^^^^^^^
-
-'event'::
- +com.google.gerrit.server.events.PatchSetCreatedEvent+
-'event-type'::
- +patchset-created+
-
-In addition to the above properties, the event also provides
-properties for the uploaded <<event-properties-patch-set,patch set>>,
-and the <<event-properties-change,change>> it belongs to.
-
-[[event-properties-RefUpdatedEvent]]
-RefUpdatedEvent
-^^^^^^^^^^^^^^^
-
-'event'::
- +com.google.gerrit.server.events.RefUpdatedEvent+
-'event-type'::
- +ref-updated+
-'project'::
- full name of the project from which a ref was updated.
-'ref'::
- git ref that has been updated (Typcially the branch, as for example
- +master+).
-'revision'::
- git commit hash the rev is pointing to now.
-'revision-old'::
- git commit hash the rev was pointing to before.
-'submitter-email'::
- email address of the user that updated the ref.
-'submitter-name'::
- name of the user that updated the ref.
-'submitter-username'::
- username of the user that updated the ref.
-
-[[event-properties-change]]
-Common properties for events on a change
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-'branch'::
- name of the branch the change belongs to.
-'change-id'::
- Change-Id for the change („I-followed by 40 hex digits” string).
-'change-number'::
- number for the change (plain integer).
-'change-url'::
- url of the change.
-'owner-email'::
- email address of the change's owner.
-'owner-name'::
- name of the change's owner.
-'owner-username'::
- username of the change's owner.
-'project'::
- full name of the project the change belongs to.
-'subject'::
- first line of the change's most recent patch set's commit message.
-'status'::
- status of the change ('null', 'NEW', 'SUBMITTED', 'DRAFT', 'MERGED',
- or 'ABANDONED' )
- +
- This property will typically be 'null' unless the used Gerrit
- incorporates
- https://gerrit-review.googlesource.com/#/c/47042/[upstream change
- 47042].
-'topic'::
- name of the topic the change belongs to.
-
-[[event-properties-patch-set]]
-Common properties for events on a patch set
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-'author-email'::
- email address of this patch set's author.
-'author-name'::
- name of this patch set's author.
-'author-username'::
- username of this patch set's author.
-'created-on'::
- Timestamp of creation of the patch set (Seconds since 1st January 1970).
-'deletions'::
- number of lines deleted by the patch set.
-'insertions'::
- number of lines inserted by the patch set.
-'is-draft'::
- 'true', if the patch set is a draft patch set, 'false' otherwise.
-'parents'::
- A list of git commit hashes that are parents to the patch set.
-'patch-set-number'::
- patch set's number within the change.
-'ref'::
- git ref for the patch set (For the 5-th patch set of change 4711, this
- will be +refs/changes/11/4711/5+).
-'revision'::
- git commit hash of the patch set
-'uploader-email'::
- email address of the user that uploaded this patch set.
-'uploader-name'::
- name of the user that uploaded this patch set.
-'uploader-username'::
- username of the user that uploaded this patch set.
-
-Actions
-~~~~~~~
-
-Parameters of the form
-----
-action = name param1 param2 ... paramN
-----
-represent the action 'name' being called with parameters 'param1',
-'param2', ... 'paramN'.
-
-'hooks-its' provides the actions:
-
-<<action-add-comment,add-comment>>::
- adds the parameters as issue comment
-<<action-add-standard-comment,add-standard-comment>>::
- adds a predefined standard comment for certain events
-<<action-add-velocity-comment,add-velocity-comment>>::
- adds a rendered Velocity template as issue comment.
-<<action-log-event,log-event>>::
- appends the event's properties to Gerrit's log.
-
-Further actions may be provided by 'hooks-its' based plugins.
-
-[[action-add-comment]]
-Action: add-comment
-^^^^^^^^^^^^^^^^^^^
-
-The 'add-comment' action adds the given parameters as comment to any associated rule.
-
-So for example
-----
-action = add-comment This is a sample command
-----
-would add a comment “This is a sample command” to associated issues.
-
-If no parameters are given, no comment gets added.
-
-[[action-add-standard-comment]]
-Action: add-standard-comment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The 'add-standard-comment' action adds predefined comments to
-associated issues for change abandoned, merged, restored, and patch
-set created events. For other events, no comment is added to the
-associated issues.
-
-The added comments contain the person responsible for the event
-(abandoner, merger, ...), the change's subject, a reason (if one has
-been given), and a link to the change.
-
-[[action-add-velocity-comment]]
-Action: add-velocity-comment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The 'add-velocity-comment' action renders a Velocity template for the
-event and adds the output as comment to any associated issue.
-
-So for example
-----
-action = add-velocity-comment TemplateName
-----
-would render the template `etc/its/templates/TemplateName.vm` add the
-output as comment to associated issues.
-
-If 'TemplateName' is “inline”, the Velocity template to render is not
-loaded from a file, but the template is built by joining the remaining
-parameters. So for example
-----
-action = add-velocity-comment inline Sample template using $subject property.
-----
-would render “Sample template using $subject property.” as Velocity
-template.
-
-If 'TemplateName' is not “inline”, further parameters get ignored.
-
-Any <<event-properties,property>> of the event may be used from
-templates. So for example +$subject+ in the above example refers to
-the event's subject property, and +$change-number+ would refer to the
-change's number.
-
-Additionally, the context's 'its' property provides an object that
-allows to format links using the its' syntax:
-
-'formatLink( url )'::
- Formats a link to a url.
- +
- So for example upon adding a comment to a change, the following rule
- formats a link to the change:
-+
-----
-[rule "formatLinkSampleRule"]
- event-type = comment-added
- action = add-velocity-comment inline Comment for change $change-number added. See ${its.formatLink($change-url)}
-----
-
-'formatLink( url, caption )'::
- Formats a link to a url using 'caption' to represent the url.
- +
- So for example upon adding a comment to a change, the following rule
- formats a link to the change using the change number as link
- capition:
-+
-----
-[rule "formatLinkSampleRule"]
- event-type = comment-added
- action = add-velocity-comment inline Comment for change ${its.formatLink($change-url, $change-number)} added.
------
-
-[[action-log-event]]
-Action: log-event
-^^^^^^^^^^^^^^^^^
-
-The 'log-event' action appends the event's properties to Gerrit's log.
-
-Logging happens at the info level per default, but can be overriden by
-adding the desired log level as parameter. Supported values are
-'error', 'warn', 'info', and 'debug'). So for example
-----
-action = log-event error
-----
-appends the event's properties to Gerrit's log at error level. All
-other parameters are ignored.
-
-This action is useful when testing rules or trying to refine
-conditions on rules, as it make the available properties visible.
-
-
-[[config-legacy]]
-Legacy configuration
---------------------
-
-In this section we present the legacy configuration that uses
-`etc/gerrit.config` directly. Please upgrade to the xref:config[new,
-more flexible approach].
-
-the
-plugin's section (e.g.: `bugzilla` for 'hooks-bugzilla') within
-`etc/gerrit.config`. In the following description, we use `itsName` as
-placeholder for the plugin's name. Be sure to replace it with the plugin's real
-name in the documentation of a 'hooks-its' based plugin (e.g.: Use `bugzilla`
-instead of `itsName` for 'hooks-bugzilla').
-
-[[itsName.commentOnChangeAbandoned]]itsName.commentOnChangeAbandoned::
-+
-If true, abandoning a change adds an ITS comment to the change's associated
-issue.
-+
-Default is `true`.
-
-[[itsName.commentOnChangeCreated]]itsName.commentOnChangeCreated::
-+
-If true, creating a change adds an ITS comment to the change's associated issue.
-+
-Default is `false`.
-
-[[itsName.commentOnChangeMerged]]itsName.commentOnChangeMerged::
-+
-If true, merging a change's patch set adds an ITS comment to the change's
-associated issue.
-+
-Default is `true`.
-
-[[itsName.commentOnChangeRestored]]itsName.commentOnChangeRestored::
-+
-If true, restoring an abandoned change adds an ITS comment to the change's
-associated issue.
-+
-Default is `true`.
-
-[[itsName.commentOnCommentAdded]]itsName.commentOnCommentAdded::
-+
-If true, adding a comment and/or review to a change in gerrit adds an ITS
-comment to the change's associated issue.
-+
-Default is `true`.
-
-[[itsName.commentOnFirstLinkedPatchSetCreated]]itsName.commentOnFirstLinkedPatchSetCreated::
-+
-If true, creating a patch set for a change adds an ITS comment to the change's
-associated issue, if the issue has not been mentioned in previous patch sets of
-the same change.
-+
-Default is `false`.
-
-[[itsName.commentOnPatchSetCreated]]itsName.commentOnPatchSetCreated::
-+
-If true, creating a patch set for a change adds an ITS comment to the change's
-associated issue.
-+
-Default is `true`.
-
-[[itsName.commentOnRefUpdatedGitWeb]]itsName.commentOnRefUpdatedGitWeb::
-+
-If true, updating a ref adds a GitWeb link to the associated issue.
-+
-Default is `true`.
+[index]: index.html
\ No newline at end of file