Changes between Version 9 and Version 10 of CommitTicketUpdater

Timestamp:

Apr 10, 2011, 8:26:07 PM (13 years ago)

Author:

AdrianFritz

Comment:

Ref. #10124 - adds "Enable", "Configure" and DRYs "Usage" sections

CommitTicketUpdater

@@ -2 +2 @@
 
 === Description ===
+
 The Commit Ticket Updater is an **optional component** which makes Trac react on keywords and ticket references found in commit log message. Referenced tickets get a new comment linking to the changeset and depending on the presence of appropriate keywords (like //closed//, //fixed//, //reopened//, etc.) the ticket status will be updated.
 
 === Hooks ===
+
 That role was fulfilled by the [source:branches/0.11-stable/trac-post-commit-hook trac-post-commit-hook] for Subversion and previous versions of Trac (up to 0.11), but starting with Trac 0.12 and [TracRepositoryAdmin multiple repository support], a more general notification solution has been adopted.
 
@@ -13 +15 @@
 
 === Location ===
-The `CommitTicketUpdater` component lives in `source:trunk/tracopt/ticket/commit_updater.py` and is maintained alongside the Trac core. It's included with every Trac installation as a plugin, but is not enabled by default because it's rooted in the `tracopt.` packages and not in `trac.`.   Therefore it needs to be explicitly activated (e.g. trough the Admin interface).
 
-=== Syntax ===
+The `CommitTicketUpdater` component lives in `source:trunk/tracopt/ticket/commit_updater.py` ([trac:browser//trunk/tracopt/ticket/commit_updater.py see it]) and is maintained alongside the Trac core. It's included with every Trac installation as a plugin, but is not enabled by default because it's rooted in the `tracopt.` packages and not in `trac.`.   Therefore it needs to be explicitly activated (e.g. trough the Admin interface).
+
+=== Enable ===
+
+ A. Trough the Admin interface ([/admin/general/plugin]), enable: //tracopt.ticket.commit_updater.*// modules
+    a. !CommitTicketUpdater     (tracopt.ticket.commit_updater.*)[[BR]][[BR]]
+ B. alternativally editing `trac.ini` file, add the following line at the appropriate section:
+{{{
+ TO BE FILLED-IN
+}}}
+
+=== Configure ===
+
+{{{
+[ticket]
+commit_ticket_update_envelope = []
+commit_ticket_update_commands.close =
+commit_ticket_update_commands.refs = <ALL>
+commit_ticket_update_check_perms = true
+commit_ticket_update_notify = true
+}}}
+
+Where,
+ a. `commit_ticket_update_envelope` sets the required commands to be enclosed in an envelope.
+     * Must be empty not to require an envelope;
+     * or contain two characters. For example, if set to "[]", then commands must be in the form of `[closes #4]`.[[BR]][[BR]]
+ a. `commit_ticket_update_commands.close`: has a space-separated list, whit commands that close tickets.
+    * Default values to **close** a ticket: //close//, //closed//, //closes//, //fix//, //fixed//, //fixes//[[BR]][[BR]]
+ a. `commit_ticket_update_commands.refs`: has a space-separated list, whit commands that add a reference to tickets.
+    * Default values to **reference** a ticket: //addresses//, //re//, //references//, //refs//, //see//
+    * If set to the special value //<ALL>//, all tickets referenced by the message will get a reference to the changeset.[[BR]][[BR]]
+ a. `commit_ticket_update_check_perms` when //true// checks that the committer has permission to perform the requested operations on the referenced tickets
+    * Values: //true//, //false//[[BR]][[BR]]
+ a. `commit_ticket_update_notify`, when //true// send ticket change notification when updating a ticket.
+    * Values: //true//, //false//
+
+=== Usage ===
+
 The basic syntax is of the form `[command] [ticketreference]`. A colon between the command and the ticket reference is allowed. The ticketreference also allows to list //multiple// ticket numbers separated by spaces and/or comma. The word 'and' is also allowed between ticket numbers.
-
-By default, you can use the following commands (edit in `trac.ini` section `[ticket]` the values `commit_ticket_update_commands.close` and  `commit_ticket_update_commands.refs` to add or change these)
-* To **close** a ticket: //close//, //closed//, //closes//, //fix//, //fixed//, //fixes//
-* To **reference** a ticket: //addresses//, //re//, //references//, //refs//, //see//
 
 You can optionally refer to tickets with the following words
@@ -29 +63 @@
 * `closed: #10`
 * `closes ticket #10`
+* `closes ticket:10`
 * `fixes #10`
 * `fixes bug: #10`