welcome to the README file.

--------------------
setup instructions
--------------------

required software:

* (for now) patchutils
* (for now) diffstat
* python
* python-cheetah
* python-pygments
* python-pysqlite2
* python-debian
* (optional) reprepro
* an httpd with wsgi support (i.e. apache2+libapache2-mod-wsgi)
* (optional) python-wsgiref (for testing outside of an httpd)
* (optional) python-profiler (for performance profiling)

first, you need a partial source archive, with the .dsc, diff.gz, Release,
and Sources.gz files available.  there's a sample config in the subdir 
./reprepro, if you don't have one handy.  Using a devious little python
filter, it will fetch the dsc and diff.gz files from the various releases
without fetching the rest of the debs/tarballs, which should keep the
archive size down a bit (though it should also work just fine on a normal
archive too).

so, you have your source archive available, and installed somewhere.
next set up a web server, and configure it to serve up the application from
wherever, using the file sample-apache2.conf as a basis.

next, take a look at the Conf module in the patchtracker directory, which
contains all the configuration items that you might need to modify to
get the script to run and generate pages as it should.  Instead of
modifying this file directly (which is tracked by git), you have the option
of placing your site config in a file "localconfig.py" in the top level
directory (the one containing this README).  The Conf module will override
its built in settings with settings in this location.

--------------------
overall design/scheme
--------------------

the whole system is loosely a read-only REST-flavoured MVC webapp (being
read-only, the "M" "C" get mixed up a bit in places).

the ultimate backing datastore is a partial source archive containing the
required source control files and debian diffs.  for efficiency and sanity
reasons much of the meta-data derived from the source archive is kept in
an updated sqlite cache, which is what is used by the rest of the system.

both the source archive and the sqlite cache are updated with the
gen-patch-info.py script.  by deafult you probably want to run:

	gen-patch-info.py -a

though during development phases you might find some of the options
of this script helpful (UTSL)

the individual patches and files are still currently taken directly
from the source archives and mangled via utlities in the diffstat
and patchutils package.

the primary port-of-call for all requests of dynamic data go through
pagehandler.py, which then delegates the request to a CmdHandler, which
in turn resolves the request to a specific Cmd subclass, which usually
corresponds to a specific view.

the webpages are generated from cheetah based templates in ./templates.