= 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.[[BR]] You can also refer to the '!SimpleEnhancer' plugin that comes with the RevtreePlugin code (see [browser:/revtreeplugin/0.10/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:browser:/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) 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.[[BR]] 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.[[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 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)[[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. * '''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 [t:wiki:WebAdmin WebAdmin] plugin interface or from your `trac.ini` file, enable the !LogEnhancer plugin.[[BR]] 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 [t:wiki:WebAdmin WebAdmin] interface. == Author/Contributors == * '''Author''' [wiki:eblot]