| | 1 | = RevtreePlugin enhancer based on log messages = |
| | 2 | |
| | 3 | == Description == |
| | 4 | |
| | 5 | !LogEnhancer is as plugin for the RevtreePlugin: it recognizes some keywords |
| | 6 | in the repository log messages to represent operations between branches. |
| | 7 | |
| | 8 | == Overview == |
| | 9 | |
| | 10 | The plugin has been developed for our team, and is therefore dedicated to the |
| | 11 | way we work with Subversion. It is delivered as a plugin, as there are few |
| | 12 | chances that you manage the files in your repository as we do. |
| | 13 | |
| | 14 | Nevertheless, the plugin can be used as a code base to write your own enhancer |
| | 15 | plugins and it demonstrates how to interface your own plugin with the |
| | 16 | RevtreePlugin.[[BR]] |
| | 17 | You can also refer to the '!SimpleEnhancer' plugin that comes |
| | 18 | with the RevtreePlugin code (see |
| | 19 | [browser:/revtreeplugin/0.10/revtree/enhancer.py enhancer.py]). |
| | 20 | |
| | 21 | == Log message description == |
| | 22 | |
| | 23 | We are using a log message format convention to work with our repository: |
| | 24 | Any change made to the repository (''copy'', ''move'', ''commit'', |
| | 25 | ''delete'') should be documented within the log message.[[BR]] |
| | 26 | Using the log message to document any change allows the developer to use his |
| | 27 | SVN client of choice (TortoiseSVN, svn CLI, ...) with no trouble. |
| | 28 | |
| | 29 | The log message format is heavily inspired from the Trac hook scripts as they |
| | 30 | have been initially provided along with Trac (see |
| | 31 | [t:browser:/branches/0.10-stable/contrib /contrib]) and a little bit enforced: |
| | 32 | 1. A log message should always start with a keyword that describes the |
| | 33 | kind of modification that is to be commited to the repository |
| | 34 | 1. There could be only one kind of modification per commit operation |
| | 35 | * As an example, a developer is not allowed to create and delete a branch |
| | 36 | within the same changeset |
| | 37 | 1. In all log messages, free text is always allowed after the initial keyword |
| | 38 | (and the mandatory options if any) |
| | 39 | |
| | 40 | To the initially contributed keywords: |
| | 41 | * '''refs #t''': used when a changeset is tied to an open ticket `t` |
| | 42 | * '''closes #t''': used when a changeset implements a feature that is tied to |
| | 43 | an open ticket `t` |
| | 44 | * '''fixes #t''': used when a changeset fixes a bug that is described in a |
| | 45 | open ticket `t` |
| | 46 | we have added a bunch of new keywords: |
| | 47 | * '''creates''': used when a developer creates a new development branch or |
| | 48 | creates a ''tag'' branch. |
| | 49 | * '''terminates''': used when a developer deletes an existing branch |
| | 50 | * '''imports''': used when a developer imports files from an external source |
| | 51 | (a Clearcase server in our team) |
| | 52 | * '''delivers [x]:[y]''': used when a developer delivers a development branch |
| | 53 | to another branch - usually to the trunk. `[x]:[y]` represents the first |
| | 54 | (`x`) and last (`y`) changeset on the source branch that are actually |
| | 55 | delivered.[[BR]] |
| | 56 | If a single changeset is delivered, the log message can be simplified as |
| | 57 | '''delivers [x]''' |
| | 58 | * '''admins''' allows the repository administrator(s) to force any kind of |
| | 59 | operations which would normally be rejected by the hook scripts |
| | 60 | |
| | 61 | The !LogEnhancer recognizes and uses the following keywords: |
| | 62 | * '''creates''': the !LogEnhancer uses this keyword to create a ''branch'' |
| | 63 | operation (from the source branch to the new branch). !LogEnhancer uses the |
| | 64 | repository path information to locate the source and the origin |
| | 65 | changeset.[[BR]] |
| | 66 | The operation is rendered as an arrow-headed spline that runs from |
| | 67 | the source changeset to the destination changeset.[[BR]] |
| | 68 | Moreover, the appearance of the destination changeset (''i.e.'' the first |
| | 69 | changeset of the newly created branch) is tweaked to signal it is the |
| | 70 | initial branch changeset: stroke and fill color are swapped |
| | 71 | * '''delivers [x]:[y]''': the !LogEnhancer uses this keyword to create a |
| | 72 | ''merge'' operation. As the SVN repository is not able to track merge |
| | 73 | operations, the !LogEnhancer needs the `x` and `y` changeset numbers to |
| | 74 | retrieve the source of the merge operation (and the source branch)[[BR]] |
| | 75 | The operation is rendered as an arrow-headed spline that runs from the |
| | 76 | youngest changeset (`y`) of the source to the destination changeset.[[BR]] |
| | 77 | The original changesets are also outlined with a rounded rectangle that |
| | 78 | represents the span of the source changesets. |
| | 79 | * '''imports''': the !LogEnhancer uses this keyword to change the appearance |
| | 80 | of the changeset (two short lines are added to the changeset circle) |
| | 81 | * '''terminates''': the !LogEnhancer uses this keyword to change the |
| | 82 | appearance of the changeset: it is filled with a black background, and the |
| | 83 | text is stroked in white color. |
| | 84 | |
| | 85 | The !LogEnhancer makes use of additional information from the SVN repository: |
| | 86 | it looks for revision properties that our team use to mark some changesets |
| | 87 | with meta information: |
| | 88 | * `st:export` indicates a (trunk) changeset that has been replicated on the |
| | 89 | external repository. The !LogEnhancer uses this property to modify the |
| | 90 | appearance of the changeset: its shape is changed from a circle to an |
| | 91 | hexagonal shape. |
| | 92 | |
| | 93 | == Installation == |
| | 94 | |
| | 95 | === Build the plugin === |
| | 96 | |
| | 97 | As with any other plugin, download the plugin code, and build a plugin egg |
| | 98 | file. The !LogEnhancer plugin source code comes with the RevtreePlugin (see |
| | 99 | RevtreePlugin#Installation), but is not built within the RevtreePlugin egg. |
| | 100 | |
| | 101 | To build the !LogEnhancer plugin, change the current directory to the |
| | 102 | `enhancers` and build the egg file: |
| | 103 | {{{ |
| | 104 | $ cd revtreeplugin/0.10/enhancers |
| | 105 | $ python setup.py bdist_egg |
| | 106 | }}} |
| | 107 | then copy the egg file to the global plugin directory or the project plugin |
| | 108 | directory |
| | 109 | |
| | 110 | === Enable the plugin === |
| | 111 | |
| | 112 | From the [t:wiki:WebAdmin WebAdmin] plugin interface or from your `trac.ini` |
| | 113 | file, enable the !LogEnhancer plugin.[[BR]] |
| | 114 | The !LogEnhancer plugin appears as `revtree.logenhancer` in the plugin list. |
| | 115 | |
| | 116 | As you have probably enabled all the revtree features with |
| | 117 | {{{ |
| | 118 | [components] |
| | 119 | revtree.* = enabled |
| | 120 | }}} |
| | 121 | when you installed the RevtreePlugin, the !LogEnhancer plugin will be loaded |
| | 122 | along with the RevtreePlugin. |
| | 123 | |
| | 124 | Nevertheless, the !LogEnhancer plugin superseeds the default !SimpleEnhancer |
| | 125 | plugin that is self-contained in the RevtreePlugin. To avoid duplicating |
| | 126 | ''creation'' operation rendering, you want to disable the default plugin: |
| | 127 | {{{ |
| | 128 | [components] |
| | 129 | revtree.* = enabled |
| | 130 | revtree.enhancer = disabled |
| | 131 | revtree.enhancer.simpleenhancer = disabled |
| | 132 | }}} |
| | 133 | |
| | 134 | You can perform the same operations from the [t:wiki:WebAdmin WebAdmin] |
| | 135 | interface. |
| | 136 | |
| | 137 | == Author/Contributors == |
| | 138 | * '''Author''' [wiki:eblot] |
