= RevtreePlugin enhancer based on log messages =

== Description ==

!LogEnhancer is a plugin for the RevtreePlugin: it recognizes some keywords 
in the repository log messages to represent operations between branches.

== Overview ==

The plugin has been developed for our team, and is therefore dedicated to the
way we work with Subversion. It is delivered as a plugin, as there are few
chances that you manage the files in your repository as we do.

Nevertheless, the plugin can be used as a code base to write your own enhancer
plugins and it demonstrates how to interface your own plugin with the 
RevtreePlugin.[[br]]
You can also refer to the '!SimpleEnhancer' plugin that comes
with the RevtreePlugin code (see 
[browser:/revtreeplugin/0.11/revtree/enhancer.py enhancer.py]).

== Log message description ==

We are using a log message format convention to work with our repository:
any change made to the repository (''copy'', ''move'', ''commit'', 
''delete'') should be documented within the log message.[[br]]
Using the log message to document any change allows the developer to use his
SVN client of choice (TortoiseSVN, svn CLI, ...) with no trouble.

The log message format is heavily inspired from the Trac hook scripts as they
have been initially provided along with Trac (see 
[t:source:branches/0.10-stable/contrib /contrib]) and a little bit enforced:
 1. A log message should always start with a keyword that describes the 
    kind of modification that is to be commited to the repository
 1. There could be only one kind of modification per commit operation
     * As an example, a developer is not allowed to create and delete a branch
       within the same changeset
 1. In all log messages, free text is always allowed after the initial keyword
    (and the mandatory options if any)

The hook scripts are available from [source:revtreeplugin/0.11/hooks].

=== Initially contributed keywords ===
 '''refs #t'''::
  used when a changeset is tied to an open ticket `t`

 '''closes #t''':: 
  used when a changeset implements a feature that is tied to an open ticket `t`

 '''fixes #t''':: 
  used when a changeset fixes a bug that is described in a open ticket `t`

=== New keywords ===

 '''creates''':: 
  used when a developer creates a new development branch or creates a ''tag'' 
  branch.[[br]]
  The !LogEnhancer uses this keyword to create a ''branch'' operation (from the
  source branch to the new branch). !LogEnhancer uses the repository path 
  information to locate the source and the origin changeset.[[br]]
  The operation is rendered as an arrow-headed spline that runs from the source
  changeset to the destination changeset.[[br]]
  Moreover, the appearance of the destination changeset (''i.e.'' the first
  changeset of the newly created branch) is tweaked to signal that it is the
  initial branch changeset: stroke and fill color are swapped 

 '''terminates'''::
  used when a developer deletes an existing branch[[br]]
  The !LogEnhancer uses this keyword to change the appearance of the changeset:
  it is filled with a black background, and the text is rendered in white color.

 '''delivers [x]:[y]''':: used when a developer delivers a development branch
  to another branch - usually to the trunk. `[x]:[y]` represents the first 
  (`x`) and last (`y`) changeset on the source branch that are actually 
  delivered.[[br]] 
  If a single changeset is delivered, the log message can be simplified as 
  `delivers [x]`[[br]]
  The !LogEnhancer uses this keyword to create a ''merge'' operation. As the 
  SVN repository (< 1.5) is not able to track merge operations, the 
  !LogEnhancer needs the `x` and `y` changeset numbers to retrieve the source
  of the merge operation (and the source branch)[[br]]
  The operation is rendered as an arrow-headed spline that runs from the
  youngest changeset (`y`) of the source to the destination changeset.[[br]]
  The original changesets are also outlined with a rounded rectangle that
  represents the span of the source changesets.

 '''brings [x]:[y]'''::
  used when a developer brings the code from a branch to another branch. 
  `[x]:[y]` represents the first (`x`) and last (`y`) changeset on the source
  branch that are actually delivered.[[br]] 
  If a single changeset is brought, the log message can be simplified as 
  `brings [x]`[[br]]
  The !LogEnhancer uses this keyword to render the operation in a very similar 
  way as it does the ''delivers'' operation, however the arrow-headed spline is
  rendered with the orange color to differentiate ''bring'' operations
  for ''deliver'' ones.

 '''admins'''::
  allows the repository administrator(s) to force any kind of operations which
  would normally be rejected by the hook scripts
   
== Installation ==

=== Build the plugin ===

As with any other plugin, download the plugin code, and build a plugin egg 
file. The !LogEnhancer plugin source code comes with the RevtreePlugin (see
RevtreePlugin#Installation), but is not built within the RevtreePlugin egg.

To build the !LogEnhancer plugin, change the current directory to the 
`enhancers` and build the egg file:
{{{
$ cd revtreeplugin/0.11/enhancers 
$ python setup.py bdist_egg
}}}
then copy the egg file to the global plugin directory or the project plugin
directory

=== Enable the plugin ===

From the [t:wiki:WebAdmin WebAdmin] plugin interface or from your `trac.ini`
file, enable the !LogEnhancer plugin.[[br]]
The !LogEnhancer plugin appears as `logenhancer.enhancer` in the plugin list.

The !LogEnhancer plugin supersedes the default !SimpleEnhancer
plugin that is self-contained in the RevtreePlugin. To avoid duplicating 
''creation'' operation rendering, you want to disable the default plugin:
{{{
[components]
revtree.* = enabled
revtree.enhancer = disabled
revtree.enhancer.simpleenhancer = disabled
logenhancer.enhancer.logenhancer = enabled
}}}

You can perform the same operations from the [t:wiki:WebAdmin WebAdmin] 
interface.

=== Plugin activation ===

Please note that the plugin needs some special SVN revision properties to 
fully operate. These properties are set by the SVN hook scripts, which are 
triggered when a user commits a new revision to the repository. This means
that revisions that have been created before the installation of the special
hook scripts do not contain the required keywords, and are therefore not 
candidates for a enhanced representation in the revtree graph. 

Please test this plugin with revisions that are created after the installation
of the hook scripts before reporting any issue.

== Author/Contributors ==
 * '''Author''' [wiki:eblot]