From b40a07693e9827d4c1a579c3a4c1f010a47ee221 Mon Sep 17 00:00:00 2001 From: richard Date: Sat, 29 Sep 2001 23:48:06 +0000 Subject: [PATCH] Bug fix for test_init on Windows. More documenation!! git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@263 57a73879-2fb5-44c3-a270-3262357dd7e2 --- doc/index.html | 383 ++++++++++++++++++++++++++++++++-------------- test/test_init.py | 10 +- 2 files changed, 276 insertions(+), 117 deletions(-) diff --git a/doc/index.html b/doc/index.html index 59834ce..dd2b714 100644 --- a/doc/index.html +++ b/doc/index.html @@ -30,6 +30,11 @@
  • Web Interface
  • E-Mail Gateway +
  • Customising Roundup +
  • Roundup's Design Document ("Implementation Guide")
  • Acknowledgements @@ -83,7 +88,8 @@ ie. "./roundup-admin init".

    The Instance

    -We'll be referring to the term "instance" a lot from now on. An instance is +We'll be referring to the term instance a lot from now on. An +instance is a directory in your filesystem that is where all the information about a live issue tracker database is stored. The data that is entered as issues, the users who access the database and the definition of the database itself @@ -240,36 +246,103 @@ To add issues, use one of the following interfaces: contents of the e-mail. -


    +

    User Guide

    Command Line Tool

    Usage: roundup-admin [-i instance home] [-u login] [-c] <command> <arguments> +

    -

    -
    Commands: -
    create classname property=value ... -
    find classname propname=value ... -
    freshen -
    get property designator[,designator]* -
    history designator -
    init [template [backend [admin password]]] -
    list classname [property] -
    retire designator[,designator]* -
    set designator[,designator]* propname=value ... -
    spec classname -
    Help: -
    roundup-admin -h -
    roundup-admin help -- this help -
    roundup-admin help -- command-specific help -
    roundup-admin morehelp -- even more detailed help -
    Options: -
    -i instance home -- specify the issue tracker "home directory" to administer -
    -u -- the user[:password] to use for commands -
    -c -- when outputting lists of data, just comma-separate them -
    + + + + +
    Options:
    -i instance home specify the issue tracker "home directory" to administer +
    -u the user[:password] to use for commands +
    -c when outputting lists of data, just comma-separate them +
    + +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Command Help
    historyhistory designator
    + Lists the journal entries for the node identified by the designator. +
    findfind classname propname=value ...
    + Find the nodes of the given class with a given property value. The + value may be either the nodeid of the linked node, or its key value. +
    listlist classname [property]
    + Lists all instances of the given class along. If the property is not + specified, the "label" property is used. The label property is tried + in order: the key, "name", "title" and then the first property, + alphabetically. +
    retireretire designator[,designator]*
    + This action indicates that a particular node is not to be retrieved by + the list or find commands, and its key value may be re-used. +
    createcreate classname property=value ...
    + This creates a new entry of the given class using the property + name=value arguments provided on the command line after the "create" + command. +
    getget property designator[,designator]*
    + Retrieves the property value of the nodes specified by the designators. +
    specspec classname
    + This lists the properties for a given class. +
    setset designator[,designator]* propname=value ...
    + Sets the property to the value for all designators given. +
    initinit [template [backend [admin password]]]
    + The command will prompt for the instance home directory (if not supplied + through INSTANCE_HOME or the -i option. The template, backend and admin + password may be specified on the command-line as arguments, in that order. +
    freshenfreshen
    + **DO NOT USE** +

    + This currently kills databases!!!! +

    + This action should generally not be used. It reads in an instance + database and writes it again. In the future, is may also update + instance code to account for changes in templates. It's probably wise + not to use it anyway. Until we're sure it won't break things... +

    helphelp [command]
    + Short help about roundup-admin or the specific command. +
    morehelpmorehelp
    + All available help from the roundup-admin tool. +

    All commands (except help) require an instance specifier. This is just the path @@ -289,6 +362,17 @@ printed results:

  • Strings are, well, strings.
  • Date values are printed in the full date format in the local time zone, and accepted in the full format or any of the partial formats explained below. + + + + + + + + + + +
    Input of...Means...
    "2000-04-17.03:45"2000-04-17.08:45:00
    "2000-04-17"2000-04-17.00:00:00
    "01-25"yyyy-01-25.00:00:00
    "08-13.22:13"yyyy-08-14.03:13:00
    "11-07.09:32:43"yyyy-11-07.14:32:43
    "14:25"yyyy-mm-dd.19:25:00
    "8:47:11"yyyy-mm-dd.13:47:11
    ".""right now"
  • Link values are printed as node designators. When given as an argument, node designators and key strings are both accepted.
  • Multilink values are printed as lists of node designators joined by commas. @@ -312,97 +396,6 @@ login may be specified as either "name" or "name:password". If either the name or password is not supplied, they are obtained from the command-line. -

    -Date format examples: - - - - - - - - - - -
    Input of...Means...
    "2000-04-17.03:45"2000-04-17.08:45:00
    "2000-04-17"2000-04-17.00:00:00
    "01-25"yyyy-01-25.00:00:00
    "08-13.22:13"yyyy-08-14.03:13:00
    "11-07.09:32:43"yyyy-11-07.14:32:43
    "14:25"yyyy-mm-dd.19:25:00
    "8:47:11"yyyy-mm-dd.13:47:11
    ".""right now"
    - -

    Specific Command help

    - -
    -history:
-    Usage: history designator
-    Show the history entries of a designator.
-
-    Lists the journal entries for the node identified by the designator.
-    
-find:
-    Usage: find classname propname=value ...
-    Find the nodes of the given class with a given property value.
-
-    Find the nodes of the given class with a given property value. The
-    value may be either the nodeid of the linked node, or its key value.
-    
-list:
-    Usage: list classname [property]
-    List the instances of a class.
-
-    Lists all instances of the given class along. If the property is not
-    specified, the  "label" property is used. The label property is tried
-    in order: the key, "name", "title" and then the first property,
-    alphabetically.
-    
-retire:
-    Usage: retire designator[,designator]*
-    Retire the node specified by designator.
-
-    This action indicates that a particular node is not to be retrieved by
-    the list or find commands, and its key value may be re-used.
-    
-create:
-    Usage: create classname property=value ...
-    Create a new entry of a given class.
-
-    This creates a new entry of the given class using the property
-    name=value arguments provided on the command line after the "create"
-    command.
-    
-get:
-    Usage: get property designator[,designator]*
-    Get the given property of one or more designator(s).
-
-    Retrieves the property value of the nodes specified by the designators.
-    
-spec:
-    Usage: spec classname
-    Show the properties for a classname.
-
-    This lists the properties for a given class.
-    
-set:
-    Usage: set designator[,designator]* propname=value ...
-    Set the given property of one or more designator(s).
-
-    Sets the property to the value for all designators given.
-    
-init:
-    Usage: init [template [backend [admin password]]]
-    Initialise a new Roundup instance.
-
-    The command will prompt for the instance home directory (if not supplied
-    through INSTANCE_HOME or the -i option. The template, backend and admin
-    password may be specified on the command-line as arguments, in that order.
-    
-freshen:
-    Usage: freshen
-    Freshen an existing instance.  **DO NOT USE**
-
-    This currently kills databases!!!!
-
-    This action should generally not be used. It reads in an instance
-    database and writes it again. In the future, is may also update
-    instance code to account for changes in templates. It's probably wise
-    not to use it anyway. Until we're sure it won't break things...
-

    Web Interface

    T.B.D. @@ -461,6 +454,164 @@ are calling the create() method to create a new node). If an auditor raises an exception, the original message is bounced back to the sender with the explanatory message given in the exception. +

    +

    Customising Roundup

    + +Instances have the following structure: + + + + + + + + + + + + + + + + + +
    dbinit.pyHolds the instance schema
    instance_config.pyHolds the basic instance configuration
    interfaces.pyDefines the Web and E-Mail interfaces for the instance
    select_db.pySelects the database back-end for the instance
    db/Holds the instance's database
    db/files/Holds the instance's upload files and messages
    detectors/Auditors and reactors for this instance
    html/Web interface templates, images and style sheets
    + +

    Instance Schema

    +An instance schema defines what data is stored in the instance's database. +The two schemas shipped with Roundup turn it into a typical software bug +tracker (the extended schema allowing for support issues as well as bugs). +Schemas are defined using Python code. The "classic" schema looks like +this: +

    +

    +    pri = Class(db, "priority", name=String(), order=String())
+    pri.setkey("name")
+    pri.create(name="critical", order="1")
+    pri.create(name="urgent", order="2")
+    pri.create(name="bug", order="3")
+    pri.create(name="feature", order="4")
+    pri.create(name="wish", order="5")
+
+    stat = Class(db, "status", name=String(), order=String())
+    stat.setkey("name")
+    stat.create(name="unread", order="1")
+    stat.create(name="deferred", order="2")
+    stat.create(name="chatting", order="3")
+    stat.create(name="need-eg", order="4")
+    stat.create(name="in-progress", order="5")
+    stat.create(name="testing", order="6")
+    stat.create(name="done-cbb", order="7")
+    stat.create(name="resolved", order="8")
+
+    keyword = Class(db, "keyword", name=String())
+    keyword.setkey("name")
+
+    user = Class(db, "user", username=String(), password=String(),
+        address=String(), realname=String(), phone=String(), organisation=String())
+    user.setkey("username")
+    user.create(username="admin", password=adminpw, address=instance_config.ADMIN_EMAIL)
+
+    msg = FileClass(db, "msg", author=Link("user"), recipients=Multilink("user"), 
+        date=Date(), summary=String(), files=Multilink("file"))
+
+    file = FileClass(db, "file", name=String(), type=String())
+
+    issue = IssueClass(db, "issue", assignedto=Link("user"),
+        topic=Multilink("keyword"), priority=Link("priority"), status=Link("status"))
+    issue.setkey('title')
+
    + +

    Class, FileClass, IssueClass - creating a new information store

    +A Class defines a particular class (or type) of data that will be +stored in the database. In the instance above, we've defined 7 classes of +information: +
    +
    priority +
    Defines the possible levels of urgency for issues. +
    status +
    Defines the possible states of processing the issue may be in. +
    keyword +
    Initially empty, will hold keywords useful for searching issues. +
    user +
    Initially holding the "admin" user, will eventually have an entry + for all users using roundup. +
    msg +
    Initially empty, will all e-mail messages sent to or generated by roundup. +
    file +
    Initially empty, will all files attached to issues. +
    issue +
    Initially emtyp, this is where the issue information is stored. +
    +

    +We define the "priority" and "status" classes to allow two things: reduction in the +amount of information stored on the issue and more powerful, accurate +searching of issues by priority and status. By only requiring a link on +the issue (which is stored as a single number) we reduce the chance +that someone mis-types a priority or status - or simply makes a new one +up. +

    + +Class +
    +Class is the basic store of information. + +

    + +FileClass +
    +FileClasses save their "content" attribute off in a separate file from the +rest of the database. This reduces the number of large entries in the +database, which generally makes databases more efficient, and also allows +us to use command-line tools to operate on the files. They are stored in +the files sub-directory of the db directory in your instance. + +

    + +IssueClass +
    +IssueClasses automatically include the "messages", "files", "nosy", and +"superseder" properties. +

    +The messages and files properties list the links to the messages and files +related to the issue. The nosy property is a list of links to users who +wish to be informed of changes to the issue - they get "CC'ed" e-mails when +messages are sent to or generated by the issue. The nosy reactor (in the +detectors directory) handles this action. The superceder link indicates an +issue which has superceded this one. +

    +They also have the dynamically generated +"creation", "activity" and "creator" properties. +

    +The value of the "creation" property is the date when an item was created, +and the value of the "activity" property is the date when any property on +the item was last edited (equivalently, these are the dates on the first +and last records in the item's journal). The "creator" property holds a +link to the user that created the issue. + +

    setkey(property)

    +Select a String property of the class to be the key property. The key +property muse be unique, and allows references to the items in the class by +the content of the key property. That is, we can refer to users by their +username, e.g. let's say that there's an issue in roundup, issue 23. There's +also a user, richard who happens to be user 2. To assign an issue to him, +we could do either of: +

    +

    roundup-admin set issue assignedto=2
    +

    +or +

    +

    roundup-admin set issue + assignedto=richard
    +

    +Note, the same thing can be done in the web and e-mail interfaces. + +

    create(information)

    +Create an item in the database. This is generally used to create items in +the "definitional" classes like "priority" and "status". + +

    Web Interface

    +

    Acknowledgements

    @@ -469,7 +620,7 @@ system on their time.

     

    -$Id: index.html,v 1.3 2001-09-29 13:44:44 richard Exp $ +$Id: index.html,v 1.4 2001-09-29 23:48:06 richard Exp $

     

    diff --git a/test/test_init.py b/test/test_init.py index c63e807..e2383cb 100644 --- a/test/test_init.py +++ b/test/test_init.py @@ -15,7 +15,7 @@ # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE, # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. # -# $Id: test_init.py,v 1.5 2001-08-29 06:23:59 richard Exp $ +# $Id: test_init.py,v 1.6 2001-09-29 23:48:06 richard Exp $ import unittest, os, shutil, errno, imp, sys @@ -30,12 +30,16 @@ class MyTestCase(unittest.TestCase): shutil.rmtree(self.dirname) except OSError, error: if error.errno != errno.ENOENT: raise + except WindowsError, error: + if error.errno != 3: raise def tearDown(self): try: shutil.rmtree(self.dirname) except OSError, error: if error.errno != errno.ENOENT: raise + except WindowsError, error: + if error.errno != 3: raise class ClassicTestCase(MyTestCase): backend = 'anydbm' @@ -136,6 +140,10 @@ def suite(): # # $Log: not supported by cvs2svn $ +# Revision 1.5 2001/08/29 06:23:59 richard +# Disabled the bsddb3 module entirely in the unit testing. See CHANGES for +# details. +# # Revision 1.4 2001/08/07 00:24:43 richard # stupid typo # -- 2.30.2