TracMonotone: Monotone Plugin for Trac
======================================================================

Warning

  The plugin is currently neither stable nor optimized for high
  performance. Use at your own risk! Some things work, others don't.

  However, your feedback is welcome!


Home

  There's a trac installation for and using the plugin located at
  http://tracmtn.1erlei.de/. Tickets for bugs and enhancement requests
  can be filed there.


Prerequisites

  * A Monotone 0.46 (or later) binary.

  * Python 2.4.

  * An installation of Trac. You can either use 0.10.X or 0.11.X, but
    support for 0.10.X is likely to be dropped soon.

  * Python setuptools >= 0.6.

  * The Python Bindings for BerkeleyDB (pyBSDdb), if you want to use
    the plugin together with mod_python. These bindings may or may not
    be part of your Python installation.


Installation

  * Create a Python egg: run 'python ./setup.py bdist_egg' in the
    plugin's toplevel dir.

  * Put the generated egg into the plugins directory of your project.

  * Add 'repository_type = mtn' and 'repository_dir = path_to_mtn_db'
    options to the [trac] section of the conf/trac.ini file of your
    project.

  * Enable the plugin by adding the option 'tracmtn.* = enabled' to
    the [components] section of the conf/trac.ini file.

  * See notes on configuration of the caching method below.

  * (Re-)start the webserver or tracd.

  * That's it :)


Configuration

  All configuration options have to be placed in the [mtn] section of
  the conf/trac.ini file.

  * The full path to the Monotone binary can be specified using the
    'mtn_binary' option.

  * A caching method for Monotone manifests, certs, changesets,
    etc. can be specified using the 'cachespec' option. The format is:
      cachespec = backend[:option1[:option2[...]]]
    
    Currently these backends are provided:
    - 'localmem[:prefix]': (default) uses local memory for caching.
      Takes an optional 'prefix' argument that can be chosen freely
      and is used to keep caches for different repositories separated.
    - 'dbmshelve:prefix': Persistent, uses Unix DBM databases named
      prefix*.{pag|dir}. All directories in prefix must exist. Not
      suited for concurrent access by more than one process.
    - 'bsddb:dir:prefix': Uses the bsddb3 binding to a persistent
      BerkeleyDB database. The directory 'dir' must be writable by
      trac. The 'prefix' is the common part of all cache files in this
      directory and can be chosen freely.

  * The 'xtracerts' option can be used to specify a (coma-separated)
    list of user-defined certs to be displayed as changeset
    properties. To control their appearance, an additional section
    [mtn-cert-<certname>] can be put in the .ini file. There are four
    options:
    - name: Property name, defaults to the cert's name.
    - text: Format string for the property, must contain %s as
      placeholder for the cert's value, defaults to "%s".
    - wikiflag: Whether the text should be interpreted as wiki text
      (True) or not (False), defaults to True.
    - htmlclass: Enables to attach special formatting to the displayed
      property, e.g. 'author', 'time', 'message' or 'changeset', has
      no default.

    Example: If you have certs named 'x-bug' that contain the number
    of a ticket a revision is related to, you could put this in
    your.ini file:

    [mtn]
    xtracerts=x-bug

    [mtn-cert-x-bug]
    name = X-Bug
    text = related to [ticket:%s]
    wikiflag = True


Selecting the Caching Method

  For better performance you should use a disk-based caching
  method. If you run a standalone version of Trac (tracd), you can
  either use 'dbmshelve' or 'bssdb'. If you use Trac via mod_python,
  you *must* use 'bsddb', because the 'dbmshelve' method doesn't
  support concurrent access by multiple processes.

  It is not recommended to use the 'localmem' method other than for
  testing purposes, because it keeps all entries in memory until the
  server process is restarted.


Known Problems/Missing Features

  * Security: The monotone select functionality is exposed. Only
    Monotone binaries prior to version 0.27 are susceptible to SQL
    injections.

  * Locking: Monotone currently does not support simultaneous access
    to the database via netsync and automate. There are various ideas
    how to overcome this situation, none of which has been fully
    implemented yet.

  * Memory leak when using the bsddb caching method, see
    http://tracmtn.1erlei.de/ticket/6.

  * Revisions are almost always printed as complete 40-char string.

  * The changeset displays doesn't show attr changes.

  * Log on a per-file basis is missing.

  * The lifetime for cached data should be adjustable.

  * Support for trac-admin is missing. (?)


Author

  Thomas Moschny <thomas.moschny@gmx.de>


Licence

  GPL, see COPYING.
