more docco work

Author: Richard Jones

CHANGES.txt

@@ -33,6 +33,9 @@ are given with the most recent entry first.
 - #614188 ] Exception in mailgw.py
 - #613310 ] traceback on onexistant items
 - #613291 ] typos in nosy list
+- handle stupid mailers that QUOTE their Re; 'Re: "[issue1] bla blah"'
+- giving a user a Role that doesn't exist doesn't break stuff any more
+- revamped user guide, customisation guide, added maintenance guide
 
 
 2002-09-13 0.5.0 beta2

TODO.txt

@@ -54,8 +54,6 @@ pending web       automagically link designators
 pending web       add checkbox-based removal/addition for multilink entries
                   (eg "add me"/"remove me" for nosy list)
 
-bug     mailgw    some f*ked mailers QUOTE their Re; "Re: "[issue1] bla blah""
 bug     docs      need to mention somewhere how sorting works
-bug     roles     giving a user a Role that doesn't exist breaks stuff
 ======= ========= =============================================================
 

doc/Makefile

@@ -3,7 +3,8 @@ STXTOHTML = -c "from docutils.core import publish;publish(writer_name='html')"
 
 SOURCE = announcement.txt customizing.txt developers.txt FAQ.txt features.txt \
     getting_started.txt glossary.txt implementation.txt index.txt \
-    installation.txt security.txt upgrading.txt user_guide.txt
+    installation.txt security.txt upgrading.txt user_guide.txt \
+    maintenance.txt
 
 COMPILED := $(SOURCE:.txt=.html)
 

doc/index.txt

@@ -9,6 +9,7 @@ Contents
 - Installation_ and `Getting Started`_ (and Upgrading_)
 - `User Guide`_
 - `Customising Roundup`_
+- `Maintaining Roundup Trackers`_
 - `Roundup's Design`_ (original_)
 - `Developing Roundup`_
 - Contact_
@@ -21,6 +22,7 @@ Contents
 .. _`Getting Started`: getting_started.html
 .. _`User Guide`: user_guide.html
 .. _`Customising Roundup`: customizing.html
+.. _`Maintaining Roundup Trackers`: maintenance.html
 .. _`Developing Roundup`: developers.html
 .. _`Roundup's Design`: design.html
 .. _original: spec.html
@@ -69,6 +71,7 @@ Engelbert Gruber,
 Juergen Hermann,
 Gordon McMillan,
 Patrick Ohly,
+Dougal Scott,
 Stefan Seefeld.
 
 

doc/installation.txt

@@ -2,7 +2,7 @@
 Installing Roundup
 ==================
 
-:Version: $Revision: 1.24 $
+:Version: $Revision: 1.25 $
 
 .. contents::
 
@@ -43,7 +43,7 @@ There's several to choose from, each with benefits and limitations:
 
 **anydbm**
   This backend is guaranteed to work on any system that Python runs on. It
-  will generally choose the best *dbm backend that is available on your system
+  will generally choose the best dbm backend that is available on your system
   (from the list dbhash, gdbm, dbm, dumbdbm). It is the least scaleable of all
   backends, but performs well enough for a smallish tracker (a couple of
   thousand issues, under fifty users, ...).
@@ -55,7 +55,8 @@ There's several to choose from, each with benefits and limitations:
   This allows it to gain some performance and scaling benefits.
 **sqlite**
   This uses the SQLite embedded RDBMS to provide a fast, scaleable backend.
-  There are no limitations.
+  There are no limitations, and it's much faster and more scaleable than the
+  dbm backends.
 **gadfly**
   This is a proof-of-concept relational database backend, not really intended
   for actual production use, although it can be. It uses the Gadfly RDBMS
@@ -64,13 +65,17 @@ There's several to choose from, each with benefits and limitations:
   setup is used.
 **metakit**
   This backend is implemented over the metakit storage system, using Mk4Py as
-  the interface. It scales much better than the *dbm backends, but has some
+  the interface. It scales much better than the dbm backends, but has some
   missing features:
 
   - you may not unset properties once they are set
   - journal retrieval is not implemented 
 
 
+Note: you may set your tracker up with the anydbm backend (which is guaranteed
+to be available) and switch to one of the other backends at any time using the
+instructions in the `maintenance documentation`_.
+
 Prerequisites
 =============
 
@@ -314,4 +319,5 @@ Next: `Getting Started`_
 .. _`roundup specification`: spec.html
 .. _`customising roundup`: customizing.html
 .. _`upgrading document`: upgrading.html
+.. _`maintenance documentation`: maintenance.html
 

doc/maintenance.txt

@@ -0,0 +1,67 @@
+============================
+Maintaining Roundup Trackers
+============================
+
+:Version: $Revision: 1.1 $
+
+.. contents::
+   :depth: 1
+
+Tasks
+=====
+
+Maintenance of Roundup can involve one of the following:
+
+1. `tracker backup`_ 
+2. `software upgrade`_
+3. `migrating backends`_
+
+
+Tracker Backup
+==============
+
+Stop the web and email frontends and to copy the contents of the tracker home
+directory to some other place using standard backup tools.
+
+Software Upgrade
+================
+
+Always make a backup of your tracker before upgrading software. Steps you may
+take:
+
+1. ensure that the unit tests run on your system
+2. copy your tracker home to a new directory
+3. follow the steps in the upgrading documentation for the new version of
+   the software
+4. test each of the admin tool, web interface and mail gateway using the new
+   version of the software
+5. stop the production web and email frontends
+6. perform the upgrade steps on the existing tracker directory
+7. upgrade the software
+8. restart your tracker
+
+Migrating Backends
+==================
+
+
+1. stop the existing tracker web and email frontends (preventing changes)
+2. use the roundup-admin tool "export" command to export the contents of
+   your tracker to disk
+3. copy the tracker home to a new directory
+4. change the backend used in the tracker home ``select_db.py`` file
+5. delete the "db" directory from the new directory
+6. use the roundup-admin "import" command to import the previous export with
+   the new tracker home
+7. test each of the admin tool, web interface and mail gateway using the new
+   backend
+8. move the old tracker home out of the way (rename to "tracker.old") and 
+   move the new tracker home into its place
+9. restart web and email frontends
+
+
+-------------------
+
+Back to `Table of Contents`_
+
+.. _`Table of Contents`: index.html
+

roundup/security.py

@@ -99,7 +99,7 @@ def hasPermission(self, permission, userid, classname=None):
         if roles is None:
             return 0
         for rolename in roles.split(','):
-            if not rolename:
+            if not rolename or not self.role.has_key(rolename):
                 continue
             # for each of the user's Roles, check the permissions
             for perm in self.role[rolename].permissions: