Update toc for new parser Change-Id: Iaff85672f2661d92b874ffa33009a75be5313b29
diff --git a/src/main/resources/Documentation/config-common.md b/src/main/resources/Documentation/config-common.md index 72d5e24..666481f 100644 --- a/src/main/resources/Documentation/config-common.md +++ b/src/main/resources/Documentation/config-common.md
@@ -1,17 +1,17 @@ -Common configuration for `its-base`-based plugins -================================================= +# 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] -* [Further common configuration details][config-common-detail] +[TOC]: # "Table of Contents" + +### Table of Contents +- [Identifying ITS ids](#identifying-its-ids) +- [Enabling ITS integration](#enabling-its-integration) +- [Associating a Gerrit project with its ITS project counterpart](#associating-a-gerrit-project-with-its-its-project-counterpart) +- [Configuring rules of when to take which actions in the ITS](#configuring-rules-of-when-to-take-which-actions-in-the-its) +- [Multiple Its](#multiple-its) +- [Further common configuration details](#further-common-configuration-details) - -[identifying-its-ids]: #identifying-its-ids -<a name="identifying-its-ids">Identifying ITS ids</a> ------------------------------------------------------ +## Identifying ITS ids In order to extract ITS ids from commit messages, @PLUGIN@ uses [commentlink][upstream-comment-link-doc]s of @@ -35,7 +35,7 @@ Sample commit message relating to bug 4711, and bug 167. ``` -[upstream-comment-link-doc]: ../../../Documentation/config-gerrit.html#commentlink +[upstream-comment-link-doc](../../../Documentation/config-gerrit.html#commentlink) By setting a `commentlink`'s `association` on the plugin's @PLUGIN@ configuration, it is possible to require commits to carry ITS references; the following @@ -72,9 +72,7 @@ using the same syntax used in the gerrit.config. Project's hierarchy will be respected when evaluating the links configuration and association policy. -[enabling-its-integration]: #enabling-its-integration -<a name="enabling-its-integration">Enabling ITS integration</a> ---------------------------------------------------------------- +## Enabling ITS integration It can be configured per project whether the issue tracker integration is enabled or not. To enable the issue tracker integration @@ -122,10 +120,7 @@ branch = ^refs/heads/stable-.* ``` -[associating-its-project]: #associating-its-project -<a name="associating-its-project">Associating a Gerrit project with its ITS -project counterpart</a> ---------------------------------------------------------------- +## Associating a Gerrit project with its ITS project counterpart To be able to make use of actions acting at the ITS project level, you must associate a Gerrit project to its ITS project counterpart. @@ -140,10 +135,7 @@ its-project = manhattan-project ``` - -[configure-rules]: #configure-rules -<a name="configure-rules">Configuring rules of when to take which actions in the ITS</a> ----------------------------------------------------------------------------------------- +## Configuring rules of when to take which actions in the ITS Setting up which event in Gerrit (E.g.: “Change Merged”, or “User ‘John Doe’ voted ‘+2’ for ‘Code-Review’ on a change”) should trigger @@ -155,9 +147,7 @@ -[multiple-its]: #multiple-its -<a name="mutiple-its">Multiple ITS</a> --------------------------------------- +## Multiple ITS Although not a common setup the @PLUGIN@ plugin supports connecting Gerrit to multiple issue tracking systems. @@ -177,15 +167,12 @@ just need to use the appropriate name to configure each plugin. +## Further common configuration details -[config-common-detail]: #config-common-detail -<a name="config-common-detail">Further common configuration details</a> ------------------------------------------------------------------------ +[common-config-commentlink](#common-config-commentlink) +[common-config-commentlinkGroupIndex](#common-config-commentlinkGroupIndex) -[common-config-commentlink]: #common-config-commentlink -[common-config-commentlinkGroupIndex]: #common-config-commentlinkGroupIndex - -<a name="common-config-commentlink">`@PLUGIN@.commentlink` +<a name="common-config-commentlink">`@PLUGIN@.commentlink`</a> : The name of the comment link to use to extract issue ids. This setting is useful to reuse the same comment link from different Its @@ -195,14 +182,14 @@ Default is `@PLUGIN@` -<a name="common-config-commentlinkGroupIndex">`@PLUGIN@.commentlinkGroupIndex` +<a name="common-config-commentlinkGroupIndex">`@PLUGIN@.commentlinkGroupIndex`</a> : The group index within `@PLUGIN@.commentlink` that holds the issue id. Default is `1`, if there are are groups within the regular expression for the `@PLUGIN@.commentlink` comment link, and the default is `0`, if there are no such groups. -<a name="common-config-dummyIssuePattern">`@PLUGIN@.dummyIssuePattern` +<a name="common-config-dummyIssuePattern">`@PLUGIN@.dummyIssuePattern`</a> : Pattern which can be specified to match a dummy issue. This setting is useful to bypass the MANDATORY check for commits matching
diff --git a/src/main/resources/Documentation/config-rulebase-common.md b/src/main/resources/Documentation/config-rulebase-common.md index 64059bf..5e57925 100644 --- a/src/main/resources/Documentation/config-rulebase-common.md +++ b/src/main/resources/Documentation/config-rulebase-common.md
@@ -1,16 +1,17 @@ -Rule base configuration -======================= +# Rule base configuration -#### Table of Contents -* [Overview][overview] -* [Rules][rules] -* [Conditions][conditions] -* [Event Properties][event-properties] -* [Actions][actions] +[TOC]: # "Table of Contents" -[overview]: #overview -<a name="overview">Overview</a> -------------------------------- +### Table of Contents +- [Overview](#overview) +- [Rule Bases Scope](#rule-bases-scope) +- [Rules](#rules) +- [Conditions](#conditions) +- [Event Properties](#event-properties) +- [Actions](#actions) + + +## Overview 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 @@ -46,9 +47,7 @@ The order of rules in a rule base file need not be respected. So in the above example, do not rely on `rule1` being evaluated before `rule2`. -[rules-scope]: #rules-scope -<a name="rules">Rule bases scope</a> -------------------------- +## Rule bases scope Rule bases can be defined in two scopes: @@ -130,9 +129,7 @@ defines their own rule base files, the global ones defined in the `gerrit_site/etc/its/` folder do not apply to this project. -[rules]: #rules -<a name="rules">Rules</a> -------------------------- +## Rules Each rule consists of three items: A name, a set of conditions, and a set of actions. @@ -151,9 +148,7 @@ 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> ------------------------------------ +## Conditions The conditions are lines of the form @@ -180,9 +175,7 @@ status = !,DRAFT ``` -[event-properties]: #event-properties -<a name="event-properties">Event Properties</a> ------------------------------------------------ +## Event Properties The properties exposed by events depend on the kind of event. @@ -235,17 +228,17 @@ 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] -* [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) +* [ChangeAbandonedEvent](#changeabandonedevent) +* [ChangeMergedEvent](#changemergedevent) +* [ChangeRestoredEvent](#changerestoredevent) +* [CommentAddedEvent](#commentaddedevent) +* [PatchSetCreatedEvent](#patchSetcreatedevent) +* [RefUpdatedEvent](#refupdatedevent) +* [Common properties for events on a change](#common-properties-for-events-on-a-change) +* [Common properties for events on a patch set](#common-properties-for-events-on-a-patch-set) -[property-association]: #property-association -### <a name="property-association">Property: `association`</a> +### Property: `association` The property `association` describes how the `issue` got associated to this event. @@ -299,8 +292,7 @@ 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> +### ChangeAbandonedEvent `abandonerEmail` : email address of the user abandoning the change. @@ -321,11 +313,10 @@ : 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]. +properties for the abandoned [Change][common-properties-for-events-on-a-change], and +its most recent [Patch Set][common-properties-for-events-on-a-patch-set]. -[event-properties-ChangeMergedEvent]: #event-properties-ChangeMergedEvent -### <a name="event-properties-ChangeMergedEvent">ChangeMergedEvent</a> +### ChangeMergedEvent `event` : `com.google.gerrit.server.events.ChangeMergedEvent` @@ -343,11 +334,10 @@ : 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]. +properties for the merged [Change][common-properties-for-events-on-a-change], and its +most recent [Patch Set][common-properties-for-events-on-a-patch-set]. -[event-properties-ChangeRestoredEvent]: #event-properties-ChangeRestoredEvent -### <a name="event-properties-ChangeRestoredEvent">ChangeRestoredEvent</a> +### ChangeRestoredEvent `event` : `com.google.gerrit.server.events.ChangeRestoredEvent` @@ -368,11 +358,10 @@ : 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]. +properties for the restored [Change][common-properties-for-events-on-a-change], and it's +most recent [Patch Set][common-properties-for-events-on-a-patch-set]. -[event-properties-CommentAddedEvent]: #event-properties-CommentAddedEvent -### <a name="event-properties-CommentAddedEvent">CommentAddedEvent</a> +### CommentAddedEvent NOTE: For consistency with the other events, the `author-...` properties of the CommentAddedEvent do not refer to the author of the @@ -393,7 +382,7 @@ : added comment itself. `event` -: `com.google.gerrit.server.events.CommentAddedEvent+ +: `com.google.gerrit.server.events.CommentAddedEvent+` `event-type` : `comment-added` @@ -407,11 +396,10 @@ : `-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]. +properties for the [Change][common-properties-for-events-on-a-change] the comment was +added for, and it's most recent [Patch Set][common-properties-for-events-on-a-patch-set]. -[event-properties-PatchSetCreatedEvent]: #event-properties-PatchSetCreatedEvent -### <a name="event-properties-PatchSetCreatedEvent">PatchSetCreatedEvent</a> +### PatchSetCreatedEvent `event` : `com.google.gerrit.server.events.PatchSetCreatedEvent` @@ -420,11 +408,10 @@ : `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. +properties for the uploaded [Patch Set][common-properties-for-events-on-a-patch-set], +and the [Change][common-properties-for-events-on-a-change] it belongs to. -[event-properties-RefUpdatedEvent]: #event-properties-RefUpdatedEvent -### <a name="event-properties-RefUpdatedEvent">RefUpdatedEvent</a> +### RefUpdatedEvent `event` : `com.google.gerrit.server.events.RefUpdatedEvent` @@ -454,8 +441,7 @@ `submitterUsername` : 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> +### Common properties for events on a change `branch` : name of the branch the change belongs to. @@ -497,8 +483,7 @@ `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> +### Common properties for events on a patch set `authorEmail` : email address of this patch set's author. @@ -540,9 +525,7 @@ `uploaderUsername` : username of the user that uploaded this patch set. -[actions]: #actions -<a name="actions">Actions</a> ------------------------------ +## Actions Lines of the form @@ -574,8 +557,7 @@ [further-actions]: config-rulebase-plugin-actions.md -[action-add-comment]: #action-add-comment -### <a name="action-add-comment">Action: add-comment</a> +### Action: add-comment The `add-comment` action adds the given parameters as comment to any associated rule. @@ -590,8 +572,7 @@ 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> +### Action: add-standard-comment The `add-standard-comment` action adds predefined comments to associated issues for change abandoned, merged, restored, and patch @@ -602,8 +583,7 @@ (abandoner, merger, ...), the change's subject, a reason (if one has been given), and a link to the change. -[action-add-soy-comment]: #action-add-soy-comment -### <a name="action-add-soy-comment">Action: add-soy-comment</a> +### Action: add-soy-comment The `add-soy-comment` action renders a Closure template (soy) for the event and adds the output as comment to any associated issue. @@ -637,8 +617,7 @@ the event's subject property, and `$changeNumber` would refer to the change's number. -[action-add-property-to-field]: #action-add-property-to-field -### <a name="action-add-property-to-field">Action: add-property-to-field</a> +### Action: add-property-to-field The `add-property-to-field` action adds an event property value to an ITS designated field. @@ -651,8 +630,7 @@ action = add-property-to-field branch labels ``` -[action-create-version-from-property]: #create-version-from-property -### <a name="create-version-from-property">Action: create-version-from-property</a> +### Action: create-version-from-property The `create-version-from-property` action creates a version in the ITS project by using an event property value as the version value. @@ -666,9 +644,7 @@ action = create-version-from-property ref ``` - -[action-log-event]: #action-log-event -### <a name="action-log-event">Action: log-event</a> +### Action: log-event The `log-event` action appends the event's properties to Gerrit's log.