Changes between Version 3 and Version 4 of RevtreePlugin


Ignore:
Timestamp:
Dec 16, 2006, 7:01:15 PM (17 years ago)
Author:
Emmanuel Blot
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