Merge "Adding documentation for configuration/action rewrite"
diff --git a/hooks-its/src/main/resources/Documentation/config.md b/hooks-its/src/main/resources/Documentation/config.md
index f817ccd..a2c4862 100644
--- a/hooks-its/src/main/resources/Documentation/config.md
+++ b/hooks-its/src/main/resources/Documentation/config.md
@@ -3,17 +3,455 @@
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
+system (ITS) plugins for Gerrit, such as
link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/hooks-bugzilla['hooks-bugzilla'],
or
link:https://gerrit-review.googlesource.com/#/admin/projects/plugins/hooks-jira['hooks-jira'].
+[[config]]
Common configuration
--------------------
-The base functionality for 'hooks-its' based plugins can be configured via the
+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.].
+
+Setting up which event in Gerrit (E.g.: “Change Merged”, or “User
+‘John Doe’ voted ‘+2’ for ‘Code-Review’ on a change”) should causes
+what 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`.
+
+
+
+[[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”) should causes what action (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
+arbirary 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 Merge” 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.
+
+A rule's name ('rule1', and 'rule2' in the above example) are
+currently not used and only provided for convenience.
+
+Each rule line setting the option 'action' is interpreted as
+action. Any other lines of a rule are 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
+~~~~~~~~~~
+
+The conditions are lines of the form
+----
+name = value1, value2, ..., valueN
+----
+and match if the event comes with a property 'name' having 'value1',
+or 'value2', or ..., or 'valueN'.
+
+
+[[event-properties]]
+Event Properties
+~~~~~~~~~~~~~~~~
+
+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. 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-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
+it's 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
+it's 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
+it's 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 it's most recent <<event-properties-patch-set,patch
+set>>.
+
+[[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.
+'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.
+'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
+~~~~~~~
+
+Lines 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.
+
+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.
+
+
+[[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
