wiki:RevtreePlugin/LogEnhancer

Version 4 (modified by eblot, 7 years ago) (diff)

Update the keyword list and add info about the plugin activation

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.
You can also refer to the 'SimpleEnhancer' plugin that comes with the RevtreePlugin code (see 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.
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 /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
  2. 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
  3. In all log messages, free text is always allowed after the initial keyword (and the mandatory options if any)

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.
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.
The operation is rendered as an arrow-headed spline that runs from the source changeset to the destination changeset.
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
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.
If a single changeset is delivered, the log message can be simplified as delivers [x]
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)
The operation is rendered as an arrow-headed spline that runs from the youngest changeset (y) of the source to the destination changeset.
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.
If a single changeset is brought, the log message can be simplified as brings [x]
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 WebAdmin plugin interface or from your trac.ini file, enable the LogEnhancer plugin.
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 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