From 5695752e7652ff6a61405f7f4f99dab9ecccef1b Mon Sep 17 00:00:00 2001 From: richard Date: Tue, 10 Sep 2002 00:45:46 +0000 Subject: [PATCH] more doc git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@1112 57a73879-2fb5-44c3-a270-3262357dd7e2 --- doc/Makefile | 2 + doc/customizing.txt | 228 +++++++++++++----------------------------- doc/design.txt | 20 ++-- doc/spec.html | 236 ++++++++++++++++++++++---------------------- doc/upgrading.txt | 14 +-- 5 files changed, 207 insertions(+), 293 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 5a55ed4..3396830 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -12,3 +12,5 @@ all: ${COMPILED} %.html: %.txt ${PYTHON} ${STXTOHTML} --report=warning -d $< $@ +clean: + rm -f ${COMPILED} diff --git a/doc/customizing.txt b/doc/customizing.txt index 03060b7..118ec15 100644 --- a/doc/customizing.txt +++ b/doc/customizing.txt @@ -2,7 +2,7 @@ Customising Roundup =================== -:Version: $Revision: 1.23 $ +:Version: $Revision: 1.24 $ .. This document borrows from the ZopeBook section on ZPT. The original is at: http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx @@ -90,18 +90,6 @@ file is a Python module. The configuration variables available are: **ADMIN_EMAIL** - ``'roundup-admin@%s'%MAIL_DOMAIN`` The email address that roundup will complain to if it runs into trouble. -**FILTER_POSITION** - ``'top'``, ``'bottom'`` or ``'top and bottom'`` - Where to place the web filtering HTML on the index page. - -**ANONYMOUS_ACCESS** - ``'deny'`` or ``'allow'`` - Deny or allow anonymous access to the web interface. - -**ANONYMOUS_REGISTER** - ``'deny'`` or ``'allow'`` - Deny or allow anonymous users to register through the web interface. - -**ANONYMOUS_REGISTER_MAIL** - ``'deny'`` or ``'allow'`` - Deny or allow anonymous users to register through the mail interface. - **MESSAGES_TO_AUTHOR** - ``'yes'`` or``'no'`` Send nosy messages to the author of the message. @@ -133,79 +121,6 @@ file is a Python module. The configuration variables available are: Default class to use in the mailgw if one isn't supplied in email subjects. To disable, comment out the variable below or leave it blank. -**HEADER_INDEX_LINKS** - ``['DEFAULT', 'UNASSIGNED', 'USER']`` - Define what index links are available in the header, and what their - labels are. Each key is used to look up one of the index specifications - below - so ``'DEFAULT'`` will use ``'DEFAULT_INDEX'``. - - Example ``DEFAULT_INDEX``:: - - { - 'LABEL': 'All Issues', - 'CLASS': 'issue', - 'SORT': ['-activity'], - 'GROUP': ['priority'], - 'FILTER': ['status'], - 'COLUMNS': ['id','activity','title','creator','assignedto'], - 'FILTERSPEC': { - 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'], - }, - } - - This defines one of the index links that appears in the - ``HEADER_INDEX_LINKS`` list. - - **LABEL** - ``'All Issues'`` - The text that appears as the link label. - **CLASS** - ``'issue'`` - The class to display the index for. - **SORT** - ``['-activity']`` - Sort by prop name, optionally preceeded with '-' to give descending or - nothing for ascending sorting. - **GROUP** - ``['priority']`` - Group by prop name, optionally preceeded with '-' or to sort in descending - or nothing for ascending order. - **FILTER** - ``['status']`` - Selects which props should be displayed in the filter section. - Default is all. - **COLUMNS** - ``['id','activity','title','creator','assignedto']`` - Selects the columns that should be displayed. Default is all. - **FILTERSPEC** - *a dictionary giving the filter specification* - The ``FILTERSPEC`` gives the filtering arguments. This selects the values - the item properties given by propname must have. - - Where the ``FILTERSPEC`` value is ``'CURRENT USER'``, it will be replaced - by the id of the logged-in user. For example:: - - 'FILTERSPEC': { - 'status': ['-1', '1', '2', '3', '4', '5', '6', '7'], - 'assignedto': 'CURRENT USER', - }, - -**HEADER_ADD_LINKS** - ``['issue']`` - List the classes that users are able to add items to. - -**HEADER_SEARCH_LINKS** - ``['issue']`` - List the classes that users can search. - -**SEARCH_FILTERS** - ``['ISSUE_FILTER', 'SUPPORT_FILTER']`` - List search filters per class. Like the INDEX entries above, each key is - used to look up one of the filter specifications below - so ``'ISSUE'`` - will use ``'ISSUE_FILTER'``. - - Example ``ISSUE_FILTER``:: - - ISSUE_FILTER = { - 'CLASS': 'issue', - 'FILTER': ['status', 'priority', 'assignedto', 'creator'] - } - - **CLASS** - ``'issue'`` - The class that the search page is for. - **FILTER** - ``['status', 'priority', 'assignedto', 'creator']`` - Selects which props should be displayed on the filter page. Default is - all. - The default config.py is given below - as you can see, the MAIL_DOMAIN must be edited before any interaction with the tracker is attempted.:: @@ -219,10 +134,6 @@ tracker is attempted.:: # The domain name used for email addresses. MAIL_DOMAIN = 'your.tracker.email.domain.example' - # the next two are only used for the standalone HTTP server. - HTTP_HOST = '' - HTTP_PORT = 9080 - # This is the directory that the database is going to be stored in DATABASE = os.path.join(INSTANCE_HOME, 'db') @@ -244,18 +155,6 @@ tracker is attempted.:: # Somewhere for roundup to log stuff internally sent to stdout or stderr LOG = os.path.join(INSTANCE_HOME, 'roundup.log') - # Where to place the web filtering HTML on the index page - FILTER_POSITION = 'bottom' # one of 'top', 'bottom', 'top and bottom' - - # Deny or allow anonymous access to the web interface - ANONYMOUS_ACCESS = 'deny' # either 'deny' or 'allow' - - # Deny or allow anonymous users to register through the web interface - ANONYMOUS_REGISTER = 'deny' # either 'deny' or 'allow' - - # Deny or allow anonymous users to register through the mail interface - ANONYMOUS_REGISTER_MAIL = 'deny' # either 'deny' or 'allow' - # Send nosy messages to the author of the message MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no' @@ -293,10 +192,15 @@ Note: if you modify the schema, you'll most likely need to edit the `web interface`_ HTML template files and `detectors`_ to reflect your changes. -A tracker schema defines what data is stored in the tracker'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:: +A tracker schema defines what data is stored in the tracker's database. +The +schemas shipped with Roundup turn it into a typical software bug tracker or +help desk. + +XXX make sure we ship the help desk + +Schemas are defined using Python code in the ``dbinit.py`` module of your +tracker. The "classic" schema looks like this:: pri = Class(db, "priority", name=String(), order=String()) pri.setkey("name") @@ -365,7 +269,7 @@ In the tracker above, we've defined 7 classes of information: Initially empty, will all files attached to issues. issue - Initially emtyp, this is where the issue information is stored. + Initially empty, 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 @@ -373,7 +277,7 @@ 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 and Nodes +Class and Items ::::::::::::::: A Class defines a particular class (or type) of data that will be stored in the @@ -387,16 +291,19 @@ Properties :::::::::: A Class is comprised of one or more properties of the following types: - * String properties are for storing arbitrary-length strings. - * Password properties are for storing encoded arbitrary-length strings. The - default encoding is defined on the roundup.password.Password class. - * Date properties store date-and-time stamps. Their values are Timestamp - objects. - * A Link property refers to a single other item selected from a specified - class. The class is part of the property; the value is an integer, the id - of the chosen item. - * A Multilink property refers to possibly many items in a specified class. - The value is a list of integers. + +* String properties are for storing arbitrary-length strings. +* Password properties are for storing encoded arbitrary-length strings. The + default encoding is defined on the roundup.password.Password class. +* Date properties store date-and-time stamps. Their values are Timestamp + objects. +* Number properties store numeric values. +* Boolean properties store on/off, yes/no, true/false values. +* A Link property refers to a single other item selected from a specified + class. The class is part of the property; the value is an integer, the id + of the chosen item. +* A Multilink property refers to possibly many items in a specified class. + The value is a list of integers. FileClass ::::::::: @@ -420,7 +327,7 @@ 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 a item was created, and +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 @@ -447,7 +354,7 @@ Note, the same thing can be done in the web and e-mail interfaces. create(information) ::::::::::::::::::: -Create a item in the database. This is generally used to create items in the +Create an item in the database. This is generally used to create items in the "definitional" classes like "priority" and "status". @@ -491,6 +398,8 @@ Sample additional detectors that have been found useful will appear in the created. The address is hard-coded into the detector, so edit it before you use it (look for the text 'team@team.host') or you'll get email errors! +XXX give the example here. + Database Content ---------------- @@ -512,46 +421,31 @@ case though, so be careful to use the right one. Use the roundup-admin interface's create, set and retire methods to add, alter or remove items from the classes in question. +XXX example Web Interface ------------- -The web interface works behind the cgi-bin/roundup.cgi or roundup-server -scripts. In both cases, the scripts determine which tracker is being accessed +The web is provided by the roundup.cgi.client module and is used by +roundup.cgi, roundup-server and ZRoundup. +In all cases, we determine which tracker is being accessed (the first part of the URL path inside the scope of the CGI handler) and pass -control on to the tracker interfaces.Client class which handles the rest of +control on to the tracker interfaces.Client class - which uses the Client class +from roundup.cgi.client - which handles the rest of the access through its main() method. This means that you can do pretty much anything you want as a web interface to your tracker. -Figuring out what is displayed -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Repurcussions of changing the tracker schema +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Most customisation of the web view can be done by modifying the templates in -the tracker **html** directory. There are several types of files in there: +If you choose to change the `tracker schema`_ you will need to ensure the web +interface knows about it: -page - defines the overall look of your tracker. When you - view an issue, it appears inside this template. When you view an index, it - also appears inside this template. -home - the default page displayed when no other page is indicated by the user -home.classlist - a special version of the default page that lists the classes in the tracker -*classname*.item - displays an item of the *classname* class -*classname*.index - displays a list of *classname* items -*classname*.search - displays a search page for *classname* items -_generic.index - used to display a list of items where there is no *classname*.index available -_generic.help - used to display a "class help" page where there is no *classname*.help -user.register - a special page just for the user class that renders the registration page -style.css - a static file that is served up as-is +1. Index, item and search pages for the relevant classes may need to have + properties added or removed, +2. The "page" template may require links to be changed, as might the "home" + page's content arguments. How requests are processed ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -652,7 +546,7 @@ edit :file Create a file and attach it to the current item's "files" property. Attach the file to the message created from - the __note if it's supplied. + the :note if it's supplied. :required=property,property,... The named properties are required to be filled in the form. @@ -713,16 +607,34 @@ search Base behaviour is to check the user can view this class. -Repurcussions of changing the tracker schema -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Default templates +~~~~~~~~~~~~~~~~~ -If you choose to change the `tracker schema`_ you will need to ensure the web -interface knows about it: +Most customisation of the web view can be done by modifying the templates in +the tracker **html** directory. There are several types of files in there: -1. Index, item and search pages for the relevant classes may need to have - properties added or removed, -2. The "page" template may require links to be changed, as might the "home" - page's content arguments. +page + defines the overall look of your tracker. When you + view an issue, it appears inside this template. When you view an index, it + also appears inside this template. +home + the default page displayed when no other page is indicated by the user +home.classlist + a special version of the default page that lists the classes in the tracker +*classname*.item + displays an item of the *classname* class +*classname*.index + displays a list of *classname* items +*classname*.search + displays a search page for *classname* items +_generic.index + used to display a list of items where there is no *classname*.index available +_generic.help + used to display a "class help" page where there is no *classname*.help +user.register + a special page just for the user class that renders the registration page +style.css + a static file that is served up as-is Overall Look - "page" template ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/design.txt b/doc/design.txt index 27a2964..f5fddba 100644 --- a/doc/design.txt +++ b/doc/design.txt @@ -189,10 +189,10 @@ Time and the current local time is 19:34:02 on 25 June 2000:: >>> Date(". + 2d") - Interval("3w") -Nodes and Classes +Items and Classes ~~~~~~~~~~~~~~~~~ -Nodes contain data in properties. To Python, these +Items contain data in properties. To Python, these properties are presented as the key-value pairs of a dictionary. Each item belongs to a class which defines the names and types of its properties. The database permits the creation @@ -212,7 +212,7 @@ the item's numeric identifier. For example, if "spam" and "eggs" are classes, the first item created in class "spam" has id 1 and designator "spam1". The first item created in class "eggs" also has id 1 but has -the distinct designator "eggs1". Node designators are +the distinct designator "eggs1". Item designators are conventionally enclosed in square brackets when mentioned in plain text. This permits a casual mention of, say, "[patch37]" in an e-mail message to be turned into an active @@ -468,7 +468,7 @@ Here is the interface provided by the hyperdatabase:: """ def getitem(self, itemid, cache=1): - ''' Return a Node convenience wrapper for the item. + ''' Return a Item convenience wrapper for the item. 'itemid' must be the id of an existing item of this class or an IndexError is raised. @@ -479,7 +479,7 @@ Here is the interface provided by the hyperdatabase:: set cache=0. ''' - class Node: + class Item: ''' A convenience wrapper for the given item. It provides a mapping interface to a single item's properties ''' @@ -1412,7 +1412,7 @@ application initialises. There will be two levels of Permission. The Class level permissions define logical permissions associated with all items of a particular class (or all -classes). The Node level permissions define logical permissions associated +classes). The Item level permissions define logical permissions associated with specific items by way of their user-linked properties. @@ -1457,7 +1457,7 @@ The security module defines:: "permission" is there for the specified classname. ''' - def hasNodePermission(self, classname, itemid, **propspec): + def hasItemPermission(self, classname, itemid, **propspec): ''' Check the named properties of the given item to see if the userid appears in them. If it does, then the user is granted this permission check. @@ -1529,13 +1529,13 @@ In the dbinit ``init()``:: user.create(username="anonymous", roles='Anonymous') Then in the code that matters, calls to ``hasPermission`` and -``hasNodePermission`` are made to determine if the user has permission +``hasItemPermission`` are made to determine if the user has permission to perform some action:: if db.security.hasPermission('issue', 'Edit', userid): # all ok - if db.security.hasNodePermission('issue', itemid, assignedto=userid): + if db.security.hasItemPermission('issue', itemid, assignedto=userid): # all ok Code in the core will make use of these methods, as should code in auditors in @@ -1553,7 +1553,7 @@ where: - the permission attribute gives a comma-separated list of permission names. These are checked in turn using ``hasPermission`` and requires one to be OK. -- the other attributes are lookups on the item using ``hasNodePermission``. If +- the other attributes are lookups on the item using ``hasItemPermission``. If the attribute value is "$userid" then the current user's userid is tested. Any of these tests must pass or the ```` check will fail. The section diff --git a/doc/spec.html b/doc/spec.html index 9bcdf08..21c1ffd 100644 --- a/doc/spec.html +++ b/doc/spec.html @@ -44,7 +44,7 @@ src="images/logo-codesourcery-medium.png" alt="[CodeSourcery Logo]" border="0"><
  • Hyperdatabase
    1. Dates and Date Arithmetic -
    2. Nodes and Classes +
    3. Items and Classes
    4. Identifiers and Designators
    5. Property Names and Types
    6. Interface Specification @@ -196,7 +196,7 @@ to stand back a bit so you don't get covered in crumbs.

      The lowest-level component to be implemented is the hyperdatabase. The hyperdatabase is intended to be a flexible data store that can hold configurable data in -records which we call nodes. +records which we call items.

      The hyperdatabase is implemented on top of the storage layer, an external module for storing its data. The storage layer could @@ -335,28 +335,28 @@ Time and the current local time is 19:34:02 on 25 June 2000. <Date 2000-06-07.00:34:02> -

      3.2. Nodes and Classes

      +

      3.2. Items and Classes

      -

      Nodes contain data in properties. To Python, these +

      Items contain data in properties. To Python, these properties are presented as the key-value pairs of a dictionary. -Each node belongs to a class which defines the names +Each item belongs to a class which defines the names and types of its properties. The database permits the creation -and modification of classes as well as nodes. +and modification of classes as well as items.

      3.3. Identifiers and Designators

      -

      Each node has a numeric identifier which is unique among -nodes in its class. The nodes are numbered sequentially +

      Each item has a numeric identifier which is unique among +items in its class. The items are numbered sequentially within each class in order of creation, starting from 1. The designator -for a node is a way to identify a node in the database, and -consists of the name of the node's class concatenated with -the node's numeric identifier. +for an item is a way to identify an item in the database, and +consists of the name of the item's class concatenated with +the item's numeric identifier.

      For example, if "spam" and "eggs" are classes, the first -node created in class "spam" has id 1 and designator "spam1". -The first node created in class "eggs" also has id 1 but has -the distinct designator "eggs1". Node designators are +item created in class "spam" has id 1 and designator "spam1". +The first item created in class "eggs" also has id 1 but has +the distinct designator "eggs1". Item designators are conventionally enclosed in square brackets when mentioned in plain text. This permits a casual mention of, say, "[patch37]" in an e-mail message to be turned into an active @@ -375,11 +375,11 @@ strings.

    7. Date properties store date-and-time stamps. Their values are Timestamp objects. -
    8. A Link property refers to a single other node +
    9. A Link property refers to a single other item selected from a specified class. The class is part of the property; -the value is an integer, the id of the chosen node. +the value is an integer, the id of the chosen item. -
    10. A Multilink property refers to possibly many nodes +
    11. A Multilink property refers to possibly many items in a specified class. The value is a list of integers. @@ -406,12 +406,12 @@ class Date: class Link: def __init__(self, classname): """An object designating a Link property that links to - nodes in a specified class.""" + items in a specified class.""" class Multilink: def __init__(self, classname): """An object designating a Multilink property that links - to nodes in a specified class.""" + to items in a specified class."""

      Here is the interface provided by the hyperdatabase. @@ -447,7 +447,7 @@ class Multilink: """ class Class: - """The handle to a particular class of nodes in a hyperdatabase.""" + """The handle to a particular class of items in a hyperdatabase.""" def __init__(self, db, classname, **properties): """Create a new class with a given name and property specification. @@ -457,10 +457,10 @@ class Class: must map names to property objects, or a TypeError is raised. """ - # Editing nodes: + # Editing items: def create(self, **propvalues): - """Create a new node of this class and return its id. + """Create a new item of this class and return its id. The keyword arguments in 'propvalues' map property names to values. The values of arguments must be acceptable for the types of their @@ -469,43 +469,43 @@ class Class: collide with other key strings or a ValueError is raised. Any other properties on this class that are missing from the 'propvalues' dictionary are set to None. If an id in a link or multilink - property does not refer to a valid node, an IndexError is raised. + property does not refer to a valid item, an IndexError is raised. """ - def get(self, nodeid, propname): - """Get the value of a property on an existing node of this class. + def get(self, itemid, propname): + """Get the value of a property on an existing item of this class. - 'nodeid' must be the id of an existing node of this class or an + 'itemid' must be the id of an existing item of this class or an IndexError is raised. 'propname' must be the name of a property of this class or a KeyError is raised. """ - def set(self, nodeid, **propvalues): - """Modify a property on an existing node of this class. + def set(self, itemid, **propvalues): + """Modify a property on an existing item of this class. - 'nodeid' must be the id of an existing node of this class or an + 'itemid' must be the id of an existing item of this class or an IndexError is raised. Each key in 'propvalues' must be the name of a property of this class or a KeyError is raised. All values in 'propvalues' must be acceptable types for their corresponding properties or a TypeError is raised. If the value of the key property is set, it must not collide with other key strings or a ValueError is raised. If the value of a Link or Multilink - property contains an invalid node id, a ValueError is raised. + property contains an invalid item id, a ValueError is raised. """ - def retire(self, nodeid): - """Retire a node. + def retire(self, itemid): + """Retire an item. - The properties on the node remain available from the get() method, - and the node's id is never reused. Retired nodes are not returned - by the find(), list(), or lookup() methods, and other nodes may + The properties on the item remain available from the get() method, + and the item's id is never reused. Retired items are not returned + by the find(), list(), or lookup() methods, and other items may reuse the values of their key properties. """ - def history(self, nodeid): - """Retrieve the journal of edits on a particular node. + def history(self, itemid): + """Retrieve the journal of edits on a particular item. - 'nodeid' must be the id of an existing node of this class or an + 'itemid' must be the id of an existing item of this class or an IndexError is raised. The returned list contains tuples of the form @@ -517,51 +517,51 @@ class Class: 'action' may be: 'create' or 'set' -- 'params' is a dictionary of property values - 'link' or 'unlink' -- 'params' is (classname, nodeid, propname) + 'link' or 'unlink' -- 'params' is (classname, itemid, propname) 'retire' -- 'params' is None """ - # Locating nodes: + # Locating items: def setkey(self, propname): """Select a String property of this class to be the key property. 'propname' must be the name of a String property of this class or None, or a TypeError is raised. The values of the key property on - all existing nodes must be unique or a ValueError is raised. + all existing items must be unique or a ValueError is raised. """ def getkey(self): """Return the name of the key property for this class or None.""" def lookup(self, keyvalue): - """Locate a particular node by its key property and return its id. + """Locate a particular item by its key property and return its id. If this class has no key property, a TypeError is raised. If the 'keyvalue' matches one of the values for the key property among - the nodes in this class, the matching node's id is returned; + the items in this class, the matching item's id is returned; otherwise a KeyError is raised. """ - def find(self, propname, nodeid): - """Get the ids of nodes in this class which link to a given node. + def find(self, propname, itemid): + """Get the ids of items in this class which link to a given item. 'propname' must be the name of a property in this class, or a KeyError is raised. That property must be a Link or Multilink - property, or a TypeError is raised. 'nodeid' must be the id of - an existing node in the class linked to by the given property, + property, or a TypeError is raised. 'itemid' must be the id of + an existing item in the class linked to by the given property, or an IndexError is raised. """ def list(self): - """Return a list of the ids of the active nodes in this class.""" + """Return a list of the ids of the active items in this class.""" def count(self): - """Get the number of nodes in this class. + """Get the number of items in this class. - If the returned integer is 'numnodes', the ids of all the nodes - in this class run from 1 to numnodes, and numnodes+1 will be the - id of the next node to be created in this class. + If the returned integer is 'numitems', the ids of all the items + in this class run from 1 to numitems, and numitems+1 will be the + id of the next item to be created in this class. """ # Manipulating properties: @@ -649,12 +649,12 @@ class Class:

      For the purposes of journalling, when a Multilink property is -set to a new list of nodes, the hyperdatabase compares the old +set to a new list of items, the hyperdatabase compares the old list to the new list. -The journal records "unlink" events for all the nodes that appear +The journal records "unlink" events for all the items that appear in the old list but not the new list, and "link" events for -all the nodes that appear in the new list but not in the old list. +all the items that appear in the new list but not in the old list.

      4. Roundup Database

      @@ -663,17 +663,17 @@ all the nodes that appear in the new list but not in the old list. hyperdatabase and mediates calls to the database. Some of the classes in the Roundup database are considered item classes. -The Roundup database layer adds detectors and user nodes, +The Roundup database layer adds detectors and user items, and on items it provides mail spools, nosy lists, and superseders.

      4.1. Reserved Classes

      Internal to this layer we reserve three special classes -of nodes that are not items. +of items that are not items.

      4.1.1. Users

      -

      Users are stored in the hyperdatabase as nodes of +

      Users are stored in the hyperdatabase as items of class "user". The "user" class has the definition:

      4.1.2. Messages

      -

      E-mail messages are represented by hyperdatabase nodes of class "msg". +

      E-mail messages are represented by hyperdatabase items of class "msg". The actual text content of the messages is stored in separate files. (There's no advantage to be gained by stuffing them into the hyperdatabase, and if messages are stored in ordinary text files, they can be grepped from the command line.) The text of a message is -saved in a file named after the message node designator (e.g. "msg23") +saved in a file named after the message item designator (e.g. "msg23") for the sake of the command interface (see below). Attachments are -stored separately and associated with "file" nodes. +stored separately and associated with "file" items. The "msg" class has the definition:

      The "author" property indicates the author of the message -(a "user" node must exist in the hyperdatabase for any messages +(a "user" item must exist in the hyperdatabase for any messages that are stored in the system). The "summary" property contains a summary of the message for display in a message index. @@ -711,9 +711,9 @@ in a message index.

      4.1.3. Files

      Submitted files are represented by hyperdatabase -nodes of class "file". Like e-mail messages, the file content +items of class "file". Like e-mail messages, the file content is stored in files outside the database, -named after the file node designator (e.g. "file17"). +named after the file item designator (e.g. "file17"). The "file" class has the definition: 

      __init__(self, storagelocator, journaltag):
         """When the Roundup database is opened by a particular user,
-        the 'journaltag' is the id of the user's "user" node."""
+        the 'journaltag' is the id of the user's "user" item."""
 
     def getclass(self, classname):
         """This method now returns an instance of either Class or
@@ -767,7 +767,7 @@ changes and additional methods.
     # New methods:
 
     def getuid(self):
-        """Return the id of the "user" node associated with the user
+        """Return the id of the "user" item associated with the user
         that owns this connection to the hyperdatabase."""
 
 class Class:
@@ -775,7 +775,7 @@ class Class:
 
     def create(self, **propvalues):
     def set(self, **propvalues):
-    def retire(self, nodeid):
+    def retire(self, itemid):
         """These operations trigger detectors and can be vetoed.  Attempts
         to modify the "creation" or "activity" properties cause a KeyError.
         """
@@ -795,25 +795,25 @@ class ItemClass(Class):
         dictionary attempts to specify any of these properties or a
         "creation" or "activity" property, a ValueError is raised."""
 
-    def get(self, nodeid, propname):
+    def get(self, itemid, propname):
     def getprops(self):
-        """In addition to the actual properties on the node, these
+        """In addition to the actual properties on the item, these
         methods provide the "creation" and "activity" properties."""
 
     # New methods:
 
-    def addmessage(self, nodeid, summary, text):
+    def addmessage(self, itemid, summary, text):
         """Add a message to an item's mail spool.
 
-        A new "msg" node is constructed using the current date, the
+        A new "msg" item is constructed using the current date, the
         user that owns the database connection as the author, and
         the specified summary text.  The "files" and "recipients"
         fields are left empty.  The given text is saved as the body
-        of the message and the node is appended to the "messages"
+        of the message and the item is appended to the "messages"
         field of the specified item.
         """
 
-    def sendmessage(self, nodeid, msgid):
+    def sendmessage(self, itemid, msgid):
         """Send a message to the members of an item's nosy list.
 
         The message is sent only to users on the nosy list who are not
@@ -885,8 +885,8 @@ provide it a chance to register its detectors.
 
      There are two kinds of detectors:
 
 
        
-
      • an auditor is triggered just before modifying an node
-
      • a reactor is triggered just after an node has been modified
+
      • an auditor is triggered just before modifying an item
+
      • a reactor is triggered just after an item has been modified
 
      
 
 
      When the Roundup database is about to perform a
@@ -904,7 +904,7 @@ for the operation.
 
      5.1. Interface Specification
      
 
 
      The audit() and react() methods
-register detectors on a given class of nodes.
+register detectors on a given class of items.
 
 
      class Class:
@@ -926,15 +926,15 @@ register detectors on a given class of nodes.
 
      Auditors are called with the arguments:
 
 
      audit(db, cl, nodeid, newdata)
      
+>audit(db, cl, itemid, newdata)
      
 
 where db is the database, cl is an
 instance of Class or ItemClass within the database, and newdata
 is a dictionary mapping property names to values.
 
 For a create()
-operation, the nodeid argument is None and newdata
-contains all of the initial property values with which the node
+operation, the itemid argument is None and newdata
+contains all of the initial property values with which the item
 is about to be created.
 
 For a set() operation, newdata
@@ -946,21 +946,21 @@ For a retire() operation, newdata is None.
 
      Reactors are called with the arguments:
 
 
      react(db, cl, nodeid, olddata)
      
+>react(db, cl, itemid, olddata)
      where db is the database, cl is an instance of Class or ItemClass within the database, and olddata is a dictionary mapping property names to values. For a create() -operation, the nodeid argument is the id of the -newly-created node and olddata is None. +operation, the itemid argument is the id of the +newly-created item and olddata is None. For a set() operation, olddata contains the names and previous values of properties that were changed. -For a retire() operation, nodeid is the -id of the retired node and olddata is None. +For a retire() operation, itemid is the +id of the retired item and olddata is None.

      5.2. Detector Example

      @@ -1002,7 +1002,7 @@ def init(db): >

      Here is another example of a detector that can allow or prevent -the creation of new nodes. In this scenario, patches for a software +the creation of new items. In this scenario, patches for a software project are submitted by sending in e-mail with an attached file, and we want to ensure that there are text/plain attachments on the message. The maintainer of the package can then apply the @@ -1065,19 +1065,19 @@ and in the printed results: time zone, and accepted in the full format or any of the partial formats explained above. -

    12. Link values are printed as node designators. When given as -an argument, node designators and key strings are both accepted. +
    13. Link values are printed as item designators. When given as +an argument, item designators and key strings are both accepted. -
    14. Multilink values are printed as lists of node designators -joined by commas. When given as an argument, node designators -and key strings are both accepted; an empty string, a single node, -or a list of nodes joined by commas is accepted. +
    15. Multilink values are printed as lists of item designators +joined by commas. When given as an argument, item designators +and key strings are both accepted; an empty string, a single item, +or a list of items joined by commas is accepted. -

      When multiple nodes are specified to the +

      When multiple items are specified to the roundup get or roundup set commands, the specified properties are retrieved or set -on all the listed nodes. +on all the listed items.

      When multiple results are returned by the roundup get or roundup find commands, they are printed one per @@ -1127,12 +1127,12 @@ extracted and examined. In a multipart/alternative message or part, we look for a text/plain subpart and ignore the other parts. The text/plain subparts are assembled to form the textual body of the message, to -be stored in the file associated with a "msg" class node. +be stored in the file associated with a "msg" class item. Any parts of other types are each stored in separate -files and given "file" class nodes that are linked to -the "msg" node. +files and given "file" class items that are linked to +the "msg" item. -

      The "summary" property on message nodes is taken from +

      The "summary" property on message items is taken from the first non-quoting section in the message body. The message body is divided into sections by blank lines. Sections where the second and all subsequent lines begin @@ -1141,18 +1141,18 @@ sections". The first line of the first non-quoting section becomes the summary of the message.

      All of the addresses in the To: and Cc: headers of the -incoming message are looked up among the user nodes, and +incoming message are looked up among the user items, and the corresponding users are placed in the "recipients" -property on the new "msg" node. The address in the From: +property on the new "msg" item. The address in the From: header similarly determines the "author" property of the -new "msg" node. +new "msg" item. The default handling for addresses that don't have corresponding users is to create new users with no passwords and a username equal to the address. (The web interface does not permit logins for users with no passwords.) If we prefer to reject mail from outside sources, we can simply register an auditor on the -"user" class that prevents the creation of user nodes with +"user" class that prevents the creation of user items with no passwords.

      The subject line of the incoming message is examined to @@ -1162,19 +1162,19 @@ in square brackets is sought as the first thing on the subject line (after skipping any "Fwd:" or "Re:" prefixes).

      If an item designator (class name and id number) is found -there, the newly created "msg" node is added to the "messages" -property for that item, and any new "file" nodes are added to +there, the newly created "msg" item is added to the "messages" +property for that item, and any new "file" items are added to the "files" property for the item.

      If just an item class name is found there, we attempt to create a new item of that class with its "messages" property -initialized to contain the new "msg" node and its "files" -property initialized to contain any new "file" nodes. +initialized to contain the new "msg" item and its "files" +property initialized to contain any new "file" items.

      Both cases may trigger detectors (in the first case we are calling the set() method to add the message to the item's spool; in the second case we are calling the -create() method to create a new node). If an auditor +create() method to create a new item). If an auditor raises an exception, the original message is bounced back to the sender with the explanatory message given in the exception. @@ -1241,7 +1241,7 @@ be displayed in an editable field.

      The display of a property is handled by functions in a displayers module. Each function accepts at least three standard arguments -- the database, class name, -and node id -- and returns a chunk of HTML. +and item id -- and returns a chunk of HTML.

      Displayer functions are triggered by <display> tags in templates. The call attribute of the tag @@ -1270,7 +1270,7 @@ displayer functions, the user interface can be highly customized.

    16. plain: display a String property directly; display a Date property in a specified time zone with an option to omit the time from the date stamp; for a Link or Multilink -property, display the key strings of the linked nodes (or the +property, display the key strings of the linked items (or the ids if the linked class has no key property)
    17. field: display a property like the @@ -1281,8 +1281,8 @@ to be edited a menu of the available choices
    18. link: for a Link or Multilink property, -display the names of the linked nodes, hyperlinked to the -item views on those nodes +display the names of the linked items, hyperlinked to the +item views on those items
    19. count: for a Multilink property, display a count of the number of links in the list @@ -1323,9 +1323,9 @@ has been added for clarity): specifier: the layout part and the filter part. The layout part consists of the query parameters that begin with colons, and it determines the way that the -properties of selected nodes are displayed. +properties of selected items are displayed. The filter part consists of all the other query parameters, -and it determines the criteria by which nodes +and it determines the criteria by which items are selected for display.

      The filter part is interactively manipulated with @@ -1339,7 +1339,7 @@ properties and the intersection of the sets of items with values matching any specified Multilink properties. -

      The example specifies an index of "issue" nodes. +

      The example specifies an index of "issue" items. Only items with a "status" of either "unread" or "in-progres" or "resolved" are displayed, and only items with "topic" values including both @@ -1409,9 +1409,9 @@ to display the values of the item's properties.

      String and Date values are sorted in the natural way. Link properties are sorted according to the value of the -"order" property on the linked nodes if it is present; or -otherwise on the key string of the linked nodes; or -finally on the node ids. Multilink properties are +"order" property on the linked items if it is present; or +otherwise on the key string of the linked items; or +finally on the item ids. Multilink properties are sorted according to how many links are present.

      8.4. Item Views

      @@ -1494,7 +1494,7 @@ detector to react by sending out this message to the nosy list).

      The spool section lists messages in the item's "messages" property. The index of messages displays the "date", "author", -and "summary" properties on the message nodes, and selecting a +and "summary" properties on the message items, and selecting a message takes you to its content.

      @@ -1503,7 +1503,7 @@ message takes you to its content.

      The design described above should be general enough to permit the use of Roundup for bug tracking, managing projects, managing patches, or holding discussions. By -using nodes of multiple types, one could deploy a system +using items of multiple types, one could deploy a system that maintains requirement specifications, catalogs bugs, and manages submitted patches, where patches could be linked to the bugs and requirements they address. diff --git a/doc/upgrading.txt b/doc/upgrading.txt index ce6ae6d..13f4613 100644 --- a/doc/upgrading.txt +++ b/doc/upgrading.txt @@ -13,9 +13,10 @@ Migrating from 0.4.x to 0.5.0 This has been a fairly major revision of Roundup: 1. Brand new, much more powerful, flexible, tasty and nutritious templating. - Unfortunately, this means all your current templates are useless. Please - don't hesitate to ask on roundup-users for help (or complete conversions - if you're completely stuck)! + Unfortunately, this means all your current templates are useless. Hopefully + the new documentation and examples will be enough to help you make the + transition. Please don't hesitate to ask on roundup-users for help (or + complete conversions if you're completely stuck)! 2. The database backed got a lot more flexible, allowing Metakit and SQL databases! The only SQL database implemented at present is gadfly, but others shouldn't be a whole lot more work. @@ -30,7 +31,7 @@ This has been a fairly major revision of Roundup: 6. Because of the above changes, the tracker configuration has seen some major changes. See below for the details. -Please, *back up your database* before you start the migration process. This +Please, **back up your database** before you start the migration process. This is as simple as copying the "db" directory and all its contents from your tracker to somewhere safe. @@ -380,9 +381,8 @@ cgi-bin directory if you're using it. --------------------- You'll want to make a backup of your current tracker html directory. You -should then copy the html directory from the Roundup source template that you -used to create your tracker, and modify it according to your local schema -changes. +should then copy the html directory from the Roundup source "classic" template +and modify it according to your local schema changes. If you need help with the new templating system, please ask questions on the roundup-users mailing list (available through the roundup project page on -- 2.30.2