README #2

Documentation for p4genreview
=============================

A Generic Review Daemon for the
Perforce Source Code Management System.
=======================================

Thomas Quinot <thomas@cuivre.fr.eu.org>

== $Id: //guest/thomas_quinot/perforce/utils/genreview/README#2 $ ==

All of the documentation and software included in the p4genreview
releases is copyrighted by Thomas Quinot. Some code included was
produced by Perforce Software and released into the public domain.

Copyright (c) 2000 by Thomas Quinot.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. Neither the name of the author, Thomas Quinot, nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THOMAS QUINOT AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THOMAS QUINOT OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

0.  Caveat
----------

This software should be considered is "testing" state. This documentation
may be incomplete, inaccurate, misleading, obscure, or more generally
inappropriate. Please feel free to send problem reports, improvement
suggestions and patches to the above email address.

Up-to-date copies of this software can be retrieved from the Perforce
Public Depot, under //guest/thomas_quinot/perforce/utils/genreview/.

1.  Contents of the distribution
--------------------------------

p4wrap.py is a utility module that gets imported by the daemon itself
  (and can also be used to write other programs that have to interface
  with the p4 command-line client).
p4genreview.py is the generic review daemon.
genreview.conf is a sample configuration file.

2. Configuration
----------------

Before you use the generic review daemon, you have to configure it.
This documentation assumes that you are familiar with the operation
of Perforce. It's best if you have already used the standard p4review daemon,
because p4genreview is a derived version of it.

The operation of the generic review deamon is driven by a configuration
file. It is a text file, which contains a sequence of options.
Each option is introduced by a keyword followed by a colon, on a line
by itself. Subsequent lines in the section must start with a tab.
Blank lines, as well as lines starting with # are ignored.

Some options are general configuration option. They should normally
appear only once at the top of your configuration file.
Options "Mailhost" and "Administrator" are used to set the name
of your SMTP server and the email address of the P4 admin.
Option "Environment" can be used to set any environment variables,
for example P4PORT, P4USER and PATH.

Once these options are set, you can define any number of "filesets".
A fileset is a set of depot file specifications, associated to an
action and a recipient list. Whenever a changelist that affects any
file matching a file specification in a fileset, the corresponding
action is invoked, and the results are mailed to the recipients.

A new fileset is introduced with option Fileset. The fileset
keyword must be followed by a unique name. The option lines
are the filespecs that make up the fileset.

An Action option must then follow. The option lines are executed
by a shell call, after substitution of the %change%, %user%, and %client%
keywords.

A Mailto option then defines the recipients for that file set.
Recipients listed in that option can be email addresses or the
special word "reviewers" by itself, which designates the set of users
interested in the change being reviewed.

    For example, as shown in the example configuration file, the following
    fileset emulates the behaviour of the standard p4review daemon:
Fileset Depot:
	//...
# Match any file
Action:
	p4 describe -s %changelist%
# Substitute changelist number, and call p4 describe -s --
# Do not forget to have the p4 client in your PATH, or call
# it with a fully qualified PATH.
Mailto: 
	reviewers
# Send the results to users who are interested in the change,
# according to their respective Reviews: fields.
     
3.  Using the daemon
--------------------

Check the path of the Python interpreter and the configuration
variables at the top of p4genreview.py, then launch it with the
name and path of the configuration file on the command line.