wiki:RevtreePlugin/LogEnhancer

Version 1 (modified by eblot, 8 years ago) (diff)

Creation

RevtreePlugin enhancer based on log messages

Description

LogEnhancer is as 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)

To the 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

we have added a bunch of new keywords:

  • creates: used when a developer creates a new development branch or creates a tag branch.
  • terminates: used when a developer deletes an existing branch
  • imports: used when a developer imports files from an external source (a Clearcase server in our team)
  • 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]
  • admins allows the repository administrator(s) to force any kind of operations which would normally be rejected by the hook scripts

The LogEnhancer recognizes and uses the following keywords:

  • creates: 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 it is the initial branch changeset: stroke and fill color are swapped
  • delivers [x]:[y]: the LogEnhancer uses this keyword to create a merge operation. As the SVN repository 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.
  • imports: the LogEnhancer uses this keyword to change the appearance of the changeset (two short lines are added to the changeset circle)
  • terminates: the LogEnhancer uses this keyword to change the appearance of the changeset: it is filled with a black background, and the text is stroked in white color.

The LogEnhancer makes use of additional information from the SVN repository: it looks for revision properties that our team use to mark some changesets with meta information:

  • st:export indicates a (trunk) changeset that has been replicated on the external repository. The LogEnhancer uses this property to modify the appearance of the changeset: its shape is changed from a circle to an hexagonal shape.

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.10/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 revtree.logenhancer in the plugin list.

As you have probably enabled all the revtree features with

[components]
revtree.* = enabled

when you installed the RevtreePlugin, the LogEnhancer plugin will be loaded along with the RevtreePlugin.

Nevertheless, the LogEnhancer plugin superseeds 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

You can perform the same operations from the WebAdmin interface.

Author/Contributors