Changes between Version 3 and Version 4 of RevtreePlugin


Ignore:
Timestamp:
Dec 16, 2006 8:01:15 PM (8 years ago)
Author:
eblot
Comment:

First useful documentation of the plugin

Legend:

Unmodified
Added
Removed
Modified
  • RevtreePlugin

    v3 v4  
    11= Revision Graph for the Version Control Browser = 
    22 
     3[[PageOutline]] 
     4 
    35== Description == 
    46 
    5 Render a graphical representation of the repository. 
    6  
    7 It superseeds the SvnCcHelpersScript/RevTree plugin: 
    8  1.  it does not rely on any Clearcase external scripts nor any SVN custom properties. 
    9  1.  it does not use the GraphvizPlugin nor the Graphviz (''dot'') tool - it is a pure Python implementation 
    10  1.  it uses the Trac repository cache, which dramatically speeds up the creation of the graph 
    11   
    12  
    13 This plugin is under heavy development, not published yet. 
     7This plugin renders a graphical representation of the repository. 
     8 
     9== Overview == 
     10 
     11This plugin creates a graph that show the changesets of the project  
     12repository. 
     13 
     14=== Filters === 
     15 
     16The user may select which changesets are to be rendered, based on the  
     17several filters: 
     18 * The main filters are mutually exclusive: 
     19   1. '''changeset range''': this filter selects a range of changesets to be  
     20      rendered 
     21   1. '''time range''': this filters selects the latest changesets of the  
     22      repository, with the following predefined time ranges: 
     23      * day, 2 days, 3 days, week, fortnight, month, 2 months, 3 months, year 
     24 * Any of the following filters can be combined to the main filter to refine  
     25 the selection: 
     26   * '''branch name''': this filter selects a single branch, along with all  
     27     branches declared as 'trunks' 
     28   * '''author''': this filter selects all the branches for which the selected  
     29     author has be a participant (''i.e.'' has committed at least one  
     30     changeset) 
     31   * '''terminated branches''': this filter allows to discard all branches  
     32     that have been 'terminated', ''i.e.'' deleted 
     33 
     34[[Image(userprefs.png)]][[BR]] 
     35''User preferences (filters)'' 
     36 
     37Two kinds of views can be selected: 
     38 * '''compact''': in this mode, the revtree graph is kept as compact as  
     39   possible, as an attempt to make all the changeset visible in the web  
     40   browser page and thereby minimize the scrolling actions. 
     41   Changesets are placed along on their branche, irrespectively of the nearby 
     42   branches. 
     43 * '''timeline''': in this mode, the revtree graph maintains a time view of 
     44   the repository: each changeset can be seen relatively to the other  
     45   changesets, whichever the changeset branch. 
     46 
     47 
     48=== User preference persistence === 
     49     
     50The plugin stores the user settings (filters) in the user session, so the  
     51latest configuration is used whenever the user selects the 'revtree' page. 
     52 
     53In some cases, the chosen filters select no changeset hence no revtree graph 
     54cannot be rendered. In such an event, a Trac error is displayed with the 
     55following message: 
     56{{{ 
     57Selected filters cannot render a revision tree 
     58}}} 
     59User settings are not saved if the filter does not permit to generate a valid 
     60revtree graph. 
     61  
     62== Limitations == 
     63 
     64There are a lot of limitations, so read them carefully. 
     65 
     66 1. the RevtreePlugin generates inlined SVG.  
     67   * SVG is only supported on modern browsers 
     68   * ''inlined SVG'' means that the plugin generates XHTML+SVG data, which are 
     69     only supported by few browsers. Many browsers that support SVG do not  
     70     accept ''inlined SVG''. 
     71 1. the RevtreePlugin only works with SVN repositories 
     72 1. it does not support SVN authz 
     73 1. it has not been thought with multiple projects per repository in mind, so 
     74    its support for this kind of configuration is probably weak 
     75 1. filters do not support multiple selections: one can only select all or one 
     76    branch, all or one author 
     77  
     78See RevtreePlugin/Limitations for a technical 'discussion' about the current 
     79limitations. 
     80 
     81=== Supported browsers === 
     82 
     83All browsers that supports ''inlined SVG'' should work. However, as it seems 
     84that only few browsers are able to cope w/ this data format, the following 
     85table tries to sum up what you can expect from your browser: 
     86 
     87{{{ 
     88#!rst 
     89+-----------+----------------+----------------+----------------+---------------------------------------------------+ 
     90| OS        + Browser        + Version        + Support        + Issues                                            + 
     91+===========+================+================+================+===================================================+ 
     92| Windows   | Firefox_       | 1.5, 2.0       | OK             |                                                   | 
     93+           +----------------+----------------+----------------+---------------------------------------------------+ 
     94|           | IE + Adobe_    | 7.0 + 3.03     | Joke           | Does not even understand the XHTML+XML MIME type  |  
     95+           +----------------+----------------+----------------+---------------------------------------------------+ 
     96|           | Opera_         | 9.02           | Partial        | Info tips are not shown                           | 
     97+-----------+----------------+----------------+----------------+---------------------------------------------------+ 
     98| OS X      | Firefox_       | 1.5, 2.0       | Buggy          | Changeset text is not show                        | 
     99+           +                +----------------+----------------+---------------------------------------------------+ 
     100|           |                | 3.0a1          | Buggy          | Issues with fonts                                 | 
     101+           +----------------+----------------+----------------+---------------------------------------------------+ 
     102|           | Camino_        | 1.0.3          | Buggy          | Changeset text is not shown                       | 
     103+           +----------------+----------------+----------------+---------------------------------------------------+ 
     104|           | OmniWeb_       | 5.5.1          | Weak           | Changeset text sometimes disappears               | 
     105|           |                |                |                | Info tips are not shown                           | 
     106+           +----------------+----------------+----------------+---------------------------------------------------+ 
     107|           | Safari_        | 2.0.4          | No             | Does not support SVG                              | 
     108+           +----------------+----------------+----------------+---------------------------------------------------+ 
     109|           | Webkit_        | r18244         | Partial        | Info tips are not shown                           | 
     110+           +----------------+----------------+----------------+---------------------------------------------------+ 
     111|           | Opera_         | 9.02           | Partial        | Info tips are not shown                           | 
     112+-----------+----------------+----------------+----------------+---------------------------------------------------+ 
     113| Linux     |                |                |                | Not tested - yet                                  | 
     114+-----------+----------------+----------------+----------------+---------------------------------------------------+ 
     115 
     116.. _Firefox: http://www.mozilla.org/firefox 
     117.. _Camino: http://www.mozilla.org/camino 
     118.. _Opera: http://www.opera.com 
     119.. _OmniWeb: http://www.omnigroup.com/applications/omniweb 
     120.. _Webkit: http://webkit.org 
     121.. _Safari: http://www.apple.com/safari/ 
     122.. _Adobe: http://www.adobe.com/svg/viewer/install/ 
     123}}} 
     124 
     125==== Additional notes ==== 
     126 
     127When info tips are not shown, links to the source browser are likely to be  
     128broken. 
    14129 
    15130== Bugs/Feature Requests ==  
     
    21136[http://trac-hacks.org/newticket?component=RevtreePlugin&owner=eblot new ticket]. 
    22137 
    23 == Download == 
     138== Installation == 
     139 
     140=== Get the plugin source code === 
     141 
     142==== Download ==== 
    24143 
    25144Download the zipped source from [download:revtreeplugin here]. 
    26145 
    27 == Source == 
    28  
    29 You can check out RevtreePlugin from [http://trac-hacks.org/svn/revtreeplugin here] using Subversion, or [source:revtreeplugin browse the source] with Trac. 
    30  
    31 == Configuration == 
     146==== Source ==== 
     147 
     148You can check out RevtreePlugin from [http://trac-hacks.org/svn/revtreeplugin here]  
     149using Subversion, or [source:revtreeplugin browse the source] with Trac. 
     150 
     151=== Build the plugin === 
     152 
     153As with any other plugin: 
     154{{{ 
     155python setup.py bdist_egg 
     156}}} 
     157 
     158=== Installation of the plugin === 
     159 
     160Copy the generated egg file (from the `dist/` directory) to your project 
     161plugin directory, or in the global plugin directory if you want to use it for 
     162several Trac projects 
     163 
     164=== Configuration === 
    32165 
    33166Revtree plugin can be configured with the help of the following settings: 
     
    37170# SVN repositories only 
    38171repository_type = svn 
    39 # Base URL is a required parameter 
     172# Base URL is a required parameter: it should be defined 
    40173base_url = none 
    41174}}} 
     
    60193}}} 
    61194 
     195Some settings deserve additional information: 
     196 * the `style` option defines the default revtree graph style. Each user  
     197   overwrites the default style the first time he updates the revtree style. 
     198 * the `reltime` option cannot be customized by the users. The admin choses 
     199   whether the time filters are based on the absolute time or the youngest 
     200   changeset in the repository. Let's say the youngest revision in the  
     201   repository has been committed three days ago: 
     202     1. if `reltime` is set, the revtree time ''starts'' three days ago as  
     203        well: if the user selects the ''last 2 days'' as a filter, the last 5 
     204        days (3+2) would be shown 
     205     1. if `reltime` is not set, the revtree time ''starts'' now: if the user 
     206        selects the ''last 2 days'', no changeset would be shown. 
     207 
     208=== Permissions === 
     209 
     210The RevtreePlugin defines a new permission `REVTREE_VIEW`. This permission 
     211should be defined for the 'revtree' link to appear in the main navigation bar, 
     212and to give access to the revtree feature. 
     213 
    62214== Example == 
    63215 
     
    68220[[ChangeLog(revtreeplugin, 3)]] 
    69221 
     222=== How is this plugin related to the previous plugin? === 
     223 
     224It superseeds the SvnCcHelpersScript/RevTree plugin: 
     225 1. it does not rely on any Clearcase external scripts nor on any SVN custom  
     226    properties. 
     227 1. it does not use the GraphvizPlugin nor the Graphviz (''dot'') tool - it  
     228    is a pure Python implementation 
     229 1. it uses the Trac repository cache, which dramatically speeds up the  
     230    creation of the graph 
     231 
     232The older plugin code has been removed from the TracHacks.org repository. 
     233 
    70234== Author/Contributors == 
    71235 
    72 '''Author:''' [wiki:eblot] [[BR]] 
    73 '''Contributors:''' 
     236==== Author ==== 
     237 * [wiki:eblot] 
     238  
     239==== Contributors ==== 
     240 
     241==== Libraries ==== 
     242 
     243The RevtreePlugin uses the following libraries: 
     244 * [http://jquery.com/ Jquery] a lightweight, yet powerful Javascript library  
     245 * [http://www2.sfk.nl/svg SVGdraw] is a Python library that enables SVG  
     246   generation 
     247