![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: e8e0c9b)
raw | patch | inline | side by side (parent: e8e0c9b)
| author | richard <richard@57a73879-2fb5-44c3-a270-3262357dd7e2> | |
| Tue, 10 Sep 2002 00:45:46 +0000 (00:45 +0000) | ||
| committer | richard <richard@57a73879-2fb5-44c3-a270-3262357dd7e2> | |
| Tue, 10 Sep 2002 00:45:46 +0000 (00:45 +0000) |
git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@1112 57a73879-2fb5-44c3-a270-3262357dd7e2
| doc/Makefile | patch | blob | history | |
| doc/customizing.txt | patch | blob | history | |
| doc/design.txt | patch | blob | history | |
| doc/spec.html | patch | blob | history | |
| doc/upgrading.txt | patch | blob | history |
diff --git a/doc/Makefile b/doc/Makefile
index 5a55ed4cdd1184af97f0bc036c3e0cbbabf34046..3396830f9098780146fb0005ce7a354881def96e 100644 (file)
--- a/doc/Makefile
+++ b/doc/Makefile
%.html: %.txt
${PYTHON} ${STXTOHTML} --report=warning -d $< $@
+clean:
+ rm -f ${COMPILED}
diff --git a/doc/customizing.txt b/doc/customizing.txt
index 03060b7d7d90e03ab0121bdf6aeae6f0bcb6445d..118ec15f377c571b835aec6a0869052513809727 100644 (file)
--- a/doc/customizing.txt
+++ b/doc/customizing.txt
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
**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.
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.::
# 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')
# 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'
`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")
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
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
::::::::::
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
:::::::::
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
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".
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
----------------
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
~~~~~~~~~~~~~~~~~~~~~~~~~~
: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.
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 27a29646db42e3247b96030831d315e6193a550d..f5fddbaab9b70ec82521ac6d7b965ad9da3f3a22 100644 (file)
--- a/doc/design.txt
+++ b/doc/design.txt
>>> Date(". + 2d") - Interval("3w")
<Date 2000-06-07.00:34:02>
-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
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
"""
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.
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
'''
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.
"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.
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
- 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 ``<require>`` check will fail. The section
diff --git a/doc/spec.html b/doc/spec.html
index 9bcdf0815977e6c7eed8fba45fd39bf578018244..21c1ffd155da1e2465186e8749c45136cae81ec8 100644 (file)
--- a/doc/spec.html
+++ b/doc/spec.html
<li>Hyperdatabase
<ol>
<li>Dates and Date Arithmetic
- <li>Nodes and Classes
+ <li>Items and Classes
<li>Identifiers and Designators
<li>Property Names and Types
<li>Interface Specification
<p>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 <em>nodes</em>.
+records which we call <em>items</em>.
<p>The hyperdatabase is implemented on top of the storage layer,
an external module for storing its data. The storage layer could
<span class="output"><Date 2000-06-07.00:34:02></span
></small></pre></blockquote>
-<h3>3.2. Nodes and Classes</h3>
+<h3>3.2. Items and Classes</h3>
-<p>Nodes contain data in <em>properties</em>. To Python, these
+<p>Items contain data in <em>properties</em>. To Python, these
properties are presented as the key-value pairs of a dictionary.
-Each node belongs to a <em>class</em> which defines the names
+Each item belongs to a <em>class</em> 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.
<h3>3.3. Identifiers and Designators</h3>
-<p>Each node has a numeric identifier which is unique among
-nodes in its class. The nodes are numbered sequentially
+<p>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 <em>designator</em>
-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.
<p>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
<li><em>Date</em> properties store date-and-time stamps.
Their values are Timestamp objects.
-<li>A <em>Link</em> property refers to a single other node
+<li>A <em>Link</em> 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.
-<li>A <em>Multilink</em> property refers to possibly many nodes
+<li>A <em>Multilink</em> property refers to possibly many items
in a specified class. The value is a list of integers.
</ul>
class <strong>Link</strong>:
def <strong>__init__</strong>(self, classname):
"""An object designating a Link property that links to
- nodes in a specified class."""
+ items in a specified class."""
class <strong>Multilink</strong>:
def <strong>__init__</strong>(self, classname):
"""An object designating a Multilink property that links
- to nodes in a specified class."""
+ to items in a specified class."""
</small></pre></blockquote>
<p>Here is the interface provided by the hyperdatabase.
"""
class <strong>Class</strong>:
- """The handle to a particular class of nodes in a hyperdatabase."""
+ """The handle to a particular class of items in a hyperdatabase."""
def <strong>__init__</strong>(self, db, classname, **properties):
"""Create a new class with a given name and property specification.
must map names to property objects, or a TypeError is raised.
"""
- # Editing nodes:
+ # Editing items:
def <strong>create</strong>(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
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 <strong>get</strong>(self, nodeid, propname):
- """Get the value of a property on an existing node of this class.
+ def <strong>get</strong>(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 <strong>set</strong>(self, nodeid, **propvalues):
- """Modify a property on an existing node of this class.
+ def <strong>set</strong>(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 <strong>retire</strong>(self, nodeid):
- """Retire a node.
+ def <strong>retire</strong>(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 <strong>history</strong>(self, nodeid):
- """Retrieve the journal of edits on a particular node.
+ def <strong>history</strong>(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
'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 <strong>setkey</strong>(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 <strong>getkey</strong>(self):
"""Return the name of the key property for this class or None."""
def <strong>lookup</strong>(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 <strong>find</strong>(self, propname, nodeid):
- """Get the ids of nodes in this class which link to a given node.
+ def <strong>find</strong>(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 <strong>list</strong>(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 <strong>count</strong>(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:
</small></pre></blockquote>
<p>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.
<p><hr>
<h2>4. Roundup Database</h2>
hyperdatabase and mediates calls to the database.
Some of the classes in the Roundup database are considered
<em>item classes</em>.
-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.
<h3>4.1. Reserved Classes</h3>
<p>Internal to this layer we reserve three special classes
-of nodes that are not items.
+of items that are not items.
<h4>4.1.1. Users</h4>
-<p>Users are stored in the hyperdatabase as nodes of
+<p>Users are stored in the hyperdatabase as items of
class "user". The "user" class has the definition:
<blockquote><pre><small
<h4>4.1.2. Messages</h4>
-<p>E-mail messages are represented by hyperdatabase nodes of class "msg".
+<p>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:
<blockquote><pre><small
></pre></blockquote>
<p>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.
<h4>4.1.3. Files</h4>
<p>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:
<blockquote><pre><small
def <strong>__init__</strong>(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 <strong>getclass</strong>(self, classname):
"""This method now returns an instance of either Class or
# New methods:
def <strong>getuid</strong>(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 <strong>Class</strong>:
def <strong>create</strong>(self, **propvalues):
def <strong>set</strong>(self, **propvalues):
- def <strong>retire</strong>(self, nodeid):
+ def <strong>retire</strong>(self, itemid):
"""These operations trigger detectors and can be vetoed. Attempts
to modify the "creation" or "activity" properties cause a KeyError.
"""
dictionary attempts to specify any of these properties or a
"creation" or "activity" property, a ValueError is raised."""
- def <strong>get</strong>(self, nodeid, propname):
+ def <strong>get</strong>(self, itemid, propname):
def <strong>getprops</strong>(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 <strong>addmessage</strong>(self, nodeid, summary, text):
+ def <strong>addmessage</strong>(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 <strong>sendmessage</strong>(self, nodeid, msgid):
+ def <strong>sendmessage</strong>(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
<p>There are two kinds of detectors:
<ul>
-<li>an <em>auditor</em> is triggered just before modifying an node
-<li>a <em>reactor</em> is triggered just after an node has been modified
+<li>an <em>auditor</em> is triggered just before modifying an item
+<li>a <em>reactor</em> is triggered just after an item has been modified
</ul>
<p>When the Roundup database is about to perform a
<h3>5.1. Interface Specification</h3>
<p>The <tt>audit()</tt> and <tt>react()</tt> methods
-register detectors on a given class of nodes.
+register detectors on a given class of items.
<blockquote><pre><small
>class Class:
<p>Auditors are called with the arguments:
<blockquote><pre><small
->audit(db, cl, nodeid, newdata)</small></pre></blockquote>
+>audit(db, cl, itemid, newdata)</small></pre></blockquote>
where <tt>db</tt> is the database, <tt>cl</tt> is an
instance of Class or ItemClass within the database, and <tt>newdata</tt>
is a dictionary mapping property names to values.
For a <tt>create()</tt>
-operation, the <tt>nodeid</tt> argument is <tt>None</tt> and <tt>newdata</tt>
-contains all of the initial property values with which the node
+operation, the <tt>itemid</tt> argument is <tt>None</tt> and <tt>newdata</tt>
+contains all of the initial property values with which the item
is about to be created.
For a <tt>set()</tt> operation, <tt>newdata</tt>
<p>Reactors are called with the arguments:
<blockquote><pre><small
->react(db, cl, nodeid, olddata)</small></pre></blockquote>
+>react(db, cl, itemid, olddata)</small></pre></blockquote>
where <tt>db</tt> is the database, <tt>cl</tt> is an
instance of Class or ItemClass within the database, and <tt>olddata</tt>
is a dictionary mapping property names to values.
For a <tt>create()</tt>
-operation, the <tt>nodeid</tt> argument is the id of the
-newly-created node and <tt>olddata</tt> is None.
+operation, the <tt>itemid</tt> argument is the id of the
+newly-created item and <tt>olddata</tt> is None.
For a <tt>set()</tt> operation, <tt>olddata</tt>
contains the names and previous values of properties that were changed.
-For a <tt>retire()</tt> operation, <tt>nodeid</tt> is the
-id of the retired node and <tt>olddata</tt> is <tt>None</tt>.
+For a <tt>retire()</tt> operation, <tt>itemid</tt> is the
+id of the retired item and <tt>olddata</tt> is <tt>None</tt>.
<h3>5.2. Detector Example</h3>
></pre></blockquote>
<p>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 <tt>text/plain</tt> attachments on
the message. The maintainer of the package can then apply the
time zone, and accepted in the full format or any of the partial
formats explained above.
-<li>Link values are printed as node designators. When given as
-an argument, node designators and key strings are both accepted.
+<li>Link values are printed as item designators. When given as
+an argument, item designators and key strings are both accepted.
-<li>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.
+<li>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.
</ul>
-<p>When multiple nodes are specified to the
+<p>When multiple items are specified to the
<tt>roundup get</tt> or <tt>roundup set</tt>
commands, the specified properties are retrieved or set
-on all the listed nodes.
+on all the listed items.
<p>When multiple results are returned by the <tt>roundup get</tt>
or <tt>roundup find</tt> commands, they are printed one per
message or part, we look for a <tt>text/plain</tt> subpart and
ignore the other parts. The <tt>text/plain</tt> 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.
-<p>The "summary" property on message nodes is taken from
+<p>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
section becomes the summary of the message.
<p>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.
<p>The subject line of the incoming message is examined to
subject line (after skipping any "Fwd:" or "Re:" prefixes).
<p>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.
<p>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.
<p>Both cases may trigger detectors (in the first case we
are calling the <tt>set()</tt> method to add the message to the
item's spool; in the second case we are calling the
-<tt>create()</tt> method to create a new node). If an auditor
+<tt>create()</tt> 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.
<p>The display of a property is handled by functions in
a <tt>displayers</tt> 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.
<p>Displayer functions are triggered by <tt><display></tt>
tags in templates. The <tt>call</tt> attribute of the tag
<li><strong>plain</strong>: 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)
<li><strong>field</strong>: display a property like the
a menu of the available choices
<li><strong>link</strong>: 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
<li><strong>count</strong>: for a Multilink property, display
a count of the number of links in the list
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.
<p>The filter part is interactively manipulated with
of items with values matching any specified Multilink
properties.
-<p>The example specifies an index of "issue" nodes.
+<p>The example specifies an index of "issue" items.
Only items with a "status" of <em>either</em>
"unread" or "in-progres" or "resolved" are displayed,
and only items with "topic" values including <em>both</em>
<p>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.
<h3>8.4. Item Views</h3>
<p>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.
<p><hr>
<p>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 ce6ae6dfaa91843df66e4ec1df283eeefd269eb8..13f4613dbaffa50cfd3ec130a3f87b73c325bd49 100644 (file)
--- a/doc/upgrading.txt
+++ b/doc/upgrading.txt
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.
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.
---------------------
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