2 | | = Revision Graph for the Version Control Browser = |
3 | | |
4 | | == Description == |
5 | | |
6 | | This plugin renders a graphical representation of the repository. |
7 | | |
8 | | The plugin collects the repository's revisions and rebuilds the branches |
9 | | based on the names of the files changed in each revision. |
10 | | |
11 | | Filters can be used to choose which branches and which revisions |
12 | | are to be displayed. |
13 | | |
14 | | Each depicted changeset is a clickable item that redirects the browser to the |
15 | | appropriate changeset view. |
16 | | |
17 | | Whenever the mouse cursor is hovered over a revtree changeset, the browser |
18 | | opens a tool tip box that shows the revision number, the author and the date |
19 | | of the revision along with the wiki-formatted log message. |
20 | | |
21 | | The plugin also shows branch cloning/tagging operations, and can be extended |
22 | | to render other kinds of operations such as merging. |
23 | | |
24 | | [[Image(changeset-tip.png)]][[BR]] |
25 | | ''Changeset info tip'' |
26 | | |
27 | | == Overview == |
28 | | |
29 | | This plugin creates a graph that shows the changesets of the project |
30 | | repository. |
31 | | |
32 | | === Filters === |
33 | | |
34 | | The user may select which changesets are to be rendered, based on several |
35 | | filters: |
| 2 | |
| 3 | = Revision Graph for the Version Control Browser |
| 4 | |
| 5 | == Description |
| 6 | |
| 7 | This plugin renders a graphical representation of the changesets of the project repository. |
| 8 | |
| 9 | The plugin collects the repository's revisions and rebuilds the branches based on the names of the files changed in each revision. |
| 10 | |
| 11 | Filters can be used to choose which branches and which revisions are to be displayed. |
| 12 | |
| 13 | Each depicted changeset is a clickable item that redirects the browser to the appropriate changeset view. |
| 14 | |
| 15 | Whenever the mouse cursor is hovered over a revtree changeset, the browser opens a tool tip box that shows the revision number, the author and the date of the revision along with the wiki-formatted log message. |
| 16 | |
| 17 | The plugin also shows branch cloning/tagging operations, and can be extended to render other kinds of operations such as merging. |
| 18 | |
| 19 | Changeset info tip: |
| 20 | |
| 21 | [[Image(changeset-tip.png)]] |
| 22 | |
| 23 | === Filters |
| 24 | |
| 25 | The user may select which changesets are to be rendered, based on several filters: |
42 | | * Any of the following filters can be combined to the main filter to refine |
43 | | the selection: |
44 | | * '''branch name''': this filter selects a single branch, along with all |
45 | | branches declared as 'trunks' |
46 | | * '''author''': this filter selects all the branches for which the selected |
47 | | author has to be a participant (''i.e.'' has committed at least one |
48 | | changeset) |
49 | | * '''show terminated branches''': this filter makes all branches visible, |
50 | | including deleted ones. Default setting hides all ''terminated'' |
| 30 | * Any of the following filters can be combined to the main filter to refine the selection: |
| 31 | * '''branch name''': this filter selects a single branch, along with all branches declared as 'trunks' |
| 32 | * '''author''': this filter selects all the branches for which the selected author has to be a participant (ie has committed at least one changeset) |
| 33 | * '''show terminated branches''': this filter makes all branches visible, including deleted ones. Default setting hides all ''terminated'' |
74 | | The plugin stores the user settings (filters) in the user session, so the |
75 | | latest configuration is used whenever the user selects the 'revtree' page. |
76 | | |
77 | | In some cases, the chosen filters select no changeset hence no revtree graph |
78 | | can be rendered. In such an event, a Trac error is displayed with the |
79 | | following message: |
| 54 | The plugin stores the user settings (filters) in the user session, so the latest configuration is used whenever the user selects the 'revtree' page. |
| 55 | |
| 56 | In some cases, the chosen filters select no changeset hence no revtree graph can be rendered. In such an event, a Trac error is displayed with the following message: |
86 | | == Limitations == |
87 | | |
88 | | There are a lot of limitations, so read them carefully. |
89 | | |
90 | | '''RevtreePlugin assumes that each revision contains changes in a single branch - |
91 | | and only one.'''[[br]] |
92 | | If it's not the case, RevtreePlugin may not work, or behave badly. |
93 | | |
94 | | See #1090 and #1191 for details about this design choice, as well as #1354 and |
95 | | #1635. |
96 | | |
97 | | CVS switchers, please be sure to read the dedicated |
98 | | [RevtreePlugin#SVNrepositoryimportedfromCVS section] |
| 62 | == Limitations |
| 63 | |
| 64 | This plugin has the following known limitations: |
| 65 | |
| 66 | '''RevtreePlugin assumes that each revision contains changes in a single branch - and only one.'''[[br]] |
| 67 | If it's not the case, RevtreePlugin may not work or behave badly. |
| 68 | |
| 69 | See #1090 and #1191 for details about this design choice, as well as #1354 and #1635. |
| 70 | |
| 71 | CVS switchers, please be sure to read the dedicated [RevtreePlugin#SVNrepositoryimportedfromCVS section] |
113 | | See RevtreePlugin/Limitations for a technical 'discussion' about the current |
114 | | limitations. |
115 | | |
116 | | The plugin output has been tested against the |
117 | | [http://validator.w3.org w3 validator] and generates |
118 | | ''Valid XHTML 1.1 plus MathML 2.0 plus SVG 1.1''. |
119 | | |
120 | | === Supported browsers === |
121 | | |
122 | | Any browser that supports ''inlined SVG'' should work. However, as it seems |
123 | | that some browsers are not able to cope with this kind of data, the following |
124 | | table sums up what you can expect from your favorite browser: |
125 | | |
126 | | Sorry, RST support is broken on Trac Hacks for now. You can get the |
127 | | compatibility matrix from [attachment:compatmatrix.txt]. |
128 | | |
129 | | The browser compatibility matrix has been created with RevtreePlugin 0.5.15 on |
130 | | April '08, 17^th^. |
131 | | |
132 | | == Installation == |
133 | | |
134 | | Trac requirement: |
135 | | * It depends on the plugin version you install. |
136 | | Please read the version requirement defined in [browser:revtreeplugin/0.11/setup.py setup.py] file, search for ''install_requires'' |
137 | | |
138 | | === Get the plugin source code === |
139 | | |
140 | | ==== Download ==== |
141 | | |
142 | | Download the zipped source from [download:revtreeplugin here]. |
143 | | |
144 | | ==== Source ==== |
145 | | |
146 | | You can check out RevtreePlugin from [http://trac-hacks.org/svn/revtreeplugin here] |
147 | | using Subversion, or [source:revtreeplugin browse the source] with Trac. |
148 | | |
149 | | === Build the plugin === |
150 | | |
151 | | As with any other plugin: |
152 | | {{{ |
| 81 | See RevtreePlugin/Limitations for a technical 'discussion' about the current limitations. |
| 82 | |
| 83 | The plugin output has been tested against the [http://validator.w3.org w3 validator] and generates ''Valid XHTML 1.1 plus MathML 2.0 plus SVG 1.1''. |
| 84 | |
| 85 | === Supported browsers |
| 86 | |
| 87 | Any browser that supports ''inlined SVG'' should work. However, as it seems that some browsers are not able to cope with this kind of data, the following table sums up what you can expect from your favorite browser: |
| 88 | |
| 89 | RST support is broken on Trac Hacks for now. You can get the compatibility matrix from [attachment:compatmatrix.txt]. |
| 90 | |
| 91 | The browser compatibility matrix has been created with RevtreePlugin 0.5.15 on April '08, 17^th^. |
| 92 | |
| 93 | == Bugs/Feature Requests |
| 94 | |
| 95 | Existing bugs and feature requests for RevtreePlugin are [query:status!=closed&component=RevtreePlugin&order=priority here]. If you have any issues, create a [/newticket?component=RevtreePlugin&cc=sylvain.delisle new ticket]. |
| 96 | |
| 97 | [[TicketQuery(component=RevtreePlugin&group=type,format=progress)]] |
| 98 | |
| 99 | == Installation |
| 100 | |
| 101 | For compatability with the Trac version you are running, check the version requirement defined in [browser:revtreeplugin/0.11/setup.py setup.py] file, search for ''install_requires''. |
| 102 | |
| 103 | The RevtreePlugin uses the following libraries: |
| 104 | * [http://genshi.edgewall.org Genshi], the XML templating system used in Trac. |
| 105 | * [http://jquery.com/ Jquery] a lightweight, yet powerful Javascript library . |
| 106 | * [http://www2.sfk.nl/svg SVGdraw] is a Python library that enables SVG generation. User Note: Seems to be included, and is nowhere else in Google. |
| 107 | |
| 108 | To build the plugin, run setup.py: |
| 109 | {{{ |
| 110 | #!sh |
156 | | === Installation of the plugin === |
157 | | |
158 | | Copy the generated egg file (from the `dist/` directory) to your project |
159 | | plugin directory, or in the global plugin directory if you want to use it for |
160 | | several Trac projects |
161 | | |
162 | | === Enabling the plugin === |
163 | | |
164 | | From the WebAdmin plugin interface or from your trac.ini file, enable the |
165 | | RevtreePlugin. |
166 | | |
167 | | In `trac.ini`, edit the ''components'' section to add the revtree entry as |
168 | | follows: |
169 | | {{{ |
| 114 | Copy the generated egg file (from the `dist/` directory) to your project plugin directory, or in the global plugin directory if you want to use it for several Trac projects. |
| 115 | |
| 116 | From the WebAdmin plugin interface or from your trac.ini file, enable the RevtreePlugin. |
| 117 | |
| 118 | In `trac.ini`, edit the ''components'' section to add the revtree entry as follows: |
| 119 | {{{ |
| 120 | #!ini |
209 | | * the `style` option defines the default revtree graph style. Each user |
210 | | overwrites the default style the first time they update the revtree style. |
211 | | * the `reltime` option cannot be customized by the users. The admin chooses |
212 | | whether the time filters are based on the absolute time or the youngest |
213 | | changeset in the repository. Let's say the youngest revision in the |
214 | | repository has been committed three days ago: |
215 | | 1. if `reltime` is set, the revtree time ''starts'' three days ago as |
216 | | well: if the user selects the ''last 2 days'' as a filter, the last 5 |
| 161 | * the `style` option defines the default revtree graph style. Each user overwrites the default style the first time they update the revtree style. |
| 162 | * the `reltime` option cannot be customized by the users. The admin chooses whether the time filters are based on the absolute time or the youngest changeset in the repository. Let's say the youngest revision in the repository has been committed three days ago: |
| 163 | 1. if `reltime` is set, the revtree time ''starts'' three days ago as well: if the user selects the ''last 2 days'' as a filter, the last 5 |
221 | | ==== Repository layout adaptation ==== |
222 | | |
223 | | The default RevtreePlugin setting is defined to work with ''single-project'' |
224 | | repository layout, as defined in the Subversion book |
225 | | [http://svnbook.red-bean.com/nightly/en/svn.branchmerge.maint.html#svn.branchmerge.maint.layout repository layout] |
226 | | section. |
227 | | |
228 | | If your repository follows a different layout, you need to tweak the branch |
229 | | regex. |
230 | | |
231 | | The following regex would better match the ''multiple-project'' repository |
232 | | layout: |
233 | | {{{ |
| 167 | ==== Repository layout adaptation |
| 168 | |
| 169 | The default RevtreePlugin setting is defined to work with ''single-project'' repository layout, as defined in the Subversion book |
| 170 | [http://svnbook.red-bean.com/nightly/en/svn.branchmerge.maint.html#svn.branchmerge.maint.layout repository layout] section. |
| 171 | |
| 172 | If your repository follows a different layout, you need to tweak the branch regex. |
| 173 | |
| 174 | The following regex would better match the ''multiple-project'' repository layout: |
| 175 | {{{ |
| 176 | #!python |
237 | | === Revtree menu item === |
238 | | |
239 | | ==== Menu selection ==== |
240 | | |
241 | | Revtree menu may either appears as a main menu item (''i.e.'' in the menu bar) |
242 | | or as a contextual menu item. |
243 | | * to make revtree link appear as a contextual menu item, define a `contexts` |
244 | | option in the `[revtree]` section of your `trac.ini` file and use a |
245 | | comma-separated list of the page contexts where the revtree menu should |
246 | | appear, ''e.g.'' |
247 | | {{{ |
| 180 | === Revtree menu item |
| 181 | |
| 182 | ==== Menu selection |
| 183 | |
| 184 | Revtree menu may either appears as a main menu item, ie in the menu bar, or as a contextual menu item. |
| 185 | * to make revtree link appear as a contextual menu item, define a `contexts` option in the `[revtree]` section of your `trac.ini` file and use a comma-separated list of the page contexts where the revtree menu should appear: |
| 186 | {{{ |
| 187 | #!ini |
259 | | ==== Position in the main menu ==== |
260 | | You can change the position of the ''revtree'' menu item using the Trac |
261 | | `mainnav` setting, see [t:wiki:TracIni#trac-section TracIni]. |
262 | | |
263 | | For example, to make the ''revtree'' menu item appear at the right hand side |
264 | | of the ''browser'' item, update the `mainnav` line as follows: |
265 | | {{{ |
| 199 | ==== Position in the main menu |
| 200 | |
| 201 | You can change the position of the ''revtree'' menu item using the Trac `mainnav` setting, see [t:wiki:TracIni#trac-section TracIni]. |
| 202 | |
| 203 | For example, to make the ''revtree'' menu item appear at the right hand side of the ''browser'' item, update the `mainnav` line as follows: |
| 204 | {{{ |
| 205 | #!ini |
280 | | == Revision tree enhancements == |
281 | | |
282 | | The RevtreePlugin has been written with customization in mind: it provides |
283 | | extension points so that one can write his own plugin(s) to add information |
284 | | to the rendered graph and enhance it. |
285 | | |
286 | | For now, there are two ways to enhance the revision tree graph: |
287 | | * Change the appearance of the rendered items, and add ''operations'' to |
288 | | the graph. An operation is a relation between two distinct branches, such |
289 | | as a merge operation.[[BR]] |
290 | | -> this extension point is dedicated to provide operations that are not |
291 | | maintained by the underlying repository. These operations can be stored |
292 | | in revision properties, log message, or any other way: it depends on how |
293 | | a team uses the repository. |
294 | | * Improve the branch placement. One of the most difficult tasks to draw a |
295 | | graphical representation of the repository is to find the best location for |
296 | | each branch. The ''best'' location depends on how a team works, what is the |
297 | | most important information to be represented, and to limit the number of |
298 | | operation intersections as much as possible.[[BR]] |
299 | | -> this extension point allows custom branch sorting. There |
300 | | are probably smart algorithms that could allow better branch |
301 | | placement. |
| 218 | == Revision tree enhancements |
| 219 | |
| 220 | The RevtreePlugin has been written with customization in mind: it provides extension points so that one can write his own plugin(s) to add information to the rendered graph and enhance it. |
| 221 | |
| 222 | For now, there are two ways to enhance the revision tree graph: |
| 223 | * Change the appearance of the rendered items, and add ''operations'' to the graph. An operation is a relation between two distinct branches, such as a merge operation.[[BR]] |
| 224 | -> this extension point is dedicated to provide operations that are not maintained by the underlying repository. These operations can be stored in revision properties, log message, or any other way: it depends on how a team uses the repository. |
| 225 | * Improve the branch placement. One of the most difficult tasks to draw a graphical representation of the repository is to find the best location for each branch. The ''best'' location depends on how a team works, what is the most important information to be represented, and to limit the number of operation intersections as much as possible.[[BR]] |
| 226 | -> this extension point allows custom branch sorting. There are probably smart algorithms that could allow better branch placement. |
306 | | * !SimpleEnhancer is a very basic enhancer that is only able to cope with |
307 | | branch creation and tagging. |
308 | | * It uses a dummy placement algorithm, which places the trunk at the center |
309 | | of the graph, and tries to reduce the number of operation intersections. |
310 | | |
311 | | === More enhancers === |
312 | | |
313 | | ==== Enhancers based on log messages ==== |
314 | | |
315 | | * the RevtreePlugin/LogEnhancer plugin is provided as an implementation example |
316 | | of the first kind of enhancer. It uses special keywords in the log messages to |
317 | | augment the revtree graph with branch creation, termination and merge |
318 | | operations. |
319 | | |
320 | | ==== Enhancers based on SVN properties ==== |
321 | | |
322 | | * the RevtreePlugin/MergeInfoEnhancer plugin can be used with the latest SVN |
323 | | release (SVN >= 1.5) to show the inter-branch merge operations of a repository. |
324 | | It is in early development stage and may not be reliable. |
| 231 | * !SimpleEnhancer is a very basic enhancer that is only able to cope with branch creation and tagging. |
| 232 | * It uses a dummy placement algorithm, which places the trunk at the center of the graph, and tries to reduce the number of operation intersections. |
| 233 | |
| 234 | === More enhancers |
| 235 | |
| 236 | ==== Enhancers based on log messages |
| 237 | |
| 238 | * the RevtreePlugin/LogEnhancer plugin is provided as an implementation example of the first kind of enhancer. It uses special keywords in the log messages to augment the revtree graph with branch creation, termination and merge operations. |
| 239 | |
| 240 | ==== Enhancers based on SVN properties |
| 241 | |
| 242 | * the RevtreePlugin/MergeInfoEnhancer plugin can be used with the latest SVN release (SVN >= 1.5) to show the inter-branch merge operations of a repository. It is in early development stage and may not be reliable. |
326 | | * the RevtreePlugin/MergeEnhancer plugin can be used in conjunction with the |
327 | | svnmerge tool to show the inter-branch merge operations of a repository. This |
328 | | enhancer is not actually maintained and is provided as an example of enhancer |
329 | | implementation |
330 | | |
331 | | == Miscelleanous == |
332 | | |
333 | | === SVN repository imported from CVS === |
334 | | |
335 | | I never used `cvs2svn` myself, but the following information might be useful |
336 | | for those who want to import their CVS-managed source code into a new SVN |
337 | | repository, and still be able to browse the repository with the RevtreePlugin. |
338 | | |
339 | | Thanks to Marcio Marchini for providing these tips: |
| 244 | * the RevtreePlugin/MergeEnhancer plugin can be used in conjunction with the svnmerge tool to show the inter-branch merge operations of a repository. This enhancer is not actually maintained and is provided as an example of enhancer implementation |
| 245 | |
| 246 | == Miscelleanous |
| 247 | |
| 248 | === SVN repository imported from CVS |
| 249 | |
| 250 | I never used `cvs2svn` myself, but the following information might be useful for those who want to import their CVS-managed source code into a new SVN repository, and still be able to browse the repository with the RevtreePlugin. Thanks to Marcio Marchini for providing these tips: |
381 | | Version 0.5.0 and above cannot be used with Trac [t:milestone:0.10 0.10] as it |
382 | | requires the [http://genshi.edgewall.org Genshi] library and uses Trac internal |
383 | | APIs that have changed since the previous release. |
384 | | |
385 | | ==== Additional notes ==== |
386 | | |
387 | | Do not forget to flush your browser cache when you update the RevtreePlugin. |
388 | | Several browsers fail to reload CSS and/or Javascript files properly, which |
389 | | may appear as plugin errors. |
390 | | |
391 | | === What about the original revtree plugin? === |
| 288 | Version 0.5.0 and above cannot be used with Trac [t:milestone:0.10 0.10] as it requires the [http://genshi.edgewall.org Genshi] library and uses Trac internal APIs that have changed since the previous release. |
| 289 | |
| 290 | ==== Additional notes |
| 291 | |
| 292 | Do not forget to flush your browser cache when you update the RevtreePlugin. Several browsers fail to reload CSS and/or Javascript files properly, which may appear as plugin errors. |
| 293 | |
| 294 | === What about the original revtree plugin? |
394 | | 1. it does not rely on any Clearcase external scripts nor on any SVN custom |
395 | | properties to build the graph, |
396 | | 1. it does not use the GraphvizPlugin nor the Graphviz (''dot'') tool to |
397 | | render the graph. It is a pure Python implementation, |
398 | | 1. it uses the Trac repository cache, which dramatically speeds up the |
399 | | generation of the graph |
400 | | 1. it can be configured and extended to support custom repository |
401 | | organization |
| 297 | 1. it does not rely on any Clearcase external scripts nor on any SVN custom properties to build the graph |
| 298 | 1. it does not use the GraphvizPlugin nor the Graphviz (''dot'') tool to render the graph. It is a pure Python implementation |
| 299 | 1. it uses the Trac repository cache, which dramatically speeds up the generation of the graph |
| 300 | 1. it can be configured and extended to support custom repository organization |
405 | | === Libraries === |
406 | | |
407 | | The RevtreePlugin uses the following libraries: |
408 | | * [http://genshi.edgewall.org Genshi], the XML templating system used in Trac |
409 | | * [http://jquery.com/ Jquery] a lightweight, yet powerful Javascript library |
410 | | * [http://www2.sfk.nl/svg SVGdraw] is a Python library that enables SVG |
411 | | generation -- User Note: Seems to be included, and is nowhere else in Google |
412 | | |
413 | | == Bugs/Feature Requests == |
414 | | |
415 | | Existing bugs and feature requests for RevtreePlugin are [query:status!=closed&component=RevtreePlugin&order=priority here]. If you have any issues, create a [/newticket?component=RevtreePlugin&cc=sylvain.delisle new ticket]. |
416 | | |
417 | | == Recent Changes == |
| 304 | == Recent Changes |