![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: f83c686)
raw | patch | inline | side by side (parent: f83c686)
| author | richard <richard@57a73879-2fb5-44c3-a270-3262357dd7e2> | |
| Tue, 10 Sep 2002 00:15:59 +0000 (00:15 +0000) | ||
| committer | richard <richard@57a73879-2fb5-44c3-a270-3262357dd7e2> | |
| Tue, 10 Sep 2002 00:15:59 +0000 (00:15 +0000) |
git-svn-id: http://svn.roundup-tracker.org/svnroot/roundup/trunk@1109 57a73879-2fb5-44c3-a270-3262357dd7e2
12 files changed:
diff --git a/doc/FAQ.txt b/doc/FAQ.txt
index f03e86682d6ced0cc889f5e1e177fbfcd6508c3d..270a3fb8aaafb73b3a37e8abe90f271c888a9a80 100644 (file)
--- a/doc/FAQ.txt
+++ b/doc/FAQ.txt
Roundup FAQ
===========
-:Version: $Revision: 1.9 $
+:Version: $Revision: 1.10 $
NOTE: This is just a grabbag, most of this should go into documentation.
Changing HTML layout
--------------------
-Note changes to the files in html take place immediatly without
-restart, even when running roundup-server.
-
-Displaying whole messages not only the summary
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Modify instance/html/msg.index change::
-
- <td><display call="plain('summary')"></td>
-
-to::
-
- <td><pre><display call="plain('content')"></pre></td>
-
-displays the whole message not only the first line and 'pre'
-prevents the browser from reformatting.
-
-Getting the nosy list picker instead of textfield
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In classic template there is plenty of space below the text field.
-So one could modify instance/html/issue.item to use it.
-
-At the file top set 'border=1' to see cell boundaries, then
-replace::
-
- <td class="form-text"><display call="field('nosy',size=20)"></td>
-
-by::
-
- <td rowspan=5 class="form-text"><display call="menu('nosy',height=10)"></td>
-
-and remove the last cell in the next four rows, either by deleting a cell
-or by reducing colspan.
-
-Want to see the issue id (the number) on the issue item display
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The number is really a central information and not an internal one.
-
-In file INSTANCE/html/issue.item displays the creator, so one could add
-the number to it.::
-
- <td class="form-text"><display call="reldate('creation', pretty=1)">
- (<display call="plain('creator')">)</td>
-
-to see::
-
- <td class="form-text"><display call="reldate('creation', pretty=1)">
- (issue<display call="plain('id')"> by <display call="plain('creator')">)</td>
-
Installation
------------
Living without a mailserver.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Remove the nosy reactor, means delete the file
-'INSTANCE/detectors/nosyreactor.py'.
+Remove the nosy reactor, means delete the tracker file
+'detectors/nosyreactor.py'.
Rights issues (MISSING)
Troubleshooting
---------------
-AttributeError: '_roundup_instance_1' module has no attribute 'open'
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For example submitting issues via roundup-mailgw breaks similar to this::
-
- Command died with status 1:
- "/usr/local/bin/python /usr/local/bin/roundup-mailgw /home/roundup".
- Command output: Traceback (most recent call last):
- File "/usr/local/bin/roundup-mailgw", line 178, in ?
- sys.exit(main(sys.argv))
- File "/usr/local/bin/roundup-mailgw", line 153, in main
- db = instance.open('admin')
- AttributeError: '_roundup_instance_1' module has no attribute 'open'
-
-Happens if the user which accesses the instance has no read right
-on 'INSTANCE/dbinit.py' or 'pyc'.
-
-If the user has no rights on the 'INSTANCE/db' the mailgw finishes,
-but is, of course, unable to add the message. A notification to
-the roundup-admin is sent, with a longer trace ending in::
-
- File "/opt/python/lib/python2.2/dbhash.py", line 16, in open
- return bsddb.hashopen(file, flag, mode)
- error: (13, 'Keine Berechtigung')
-
-Replace 'Keine Berechtigung' by 'Not permitted' or ...
-
-An easy way to test whether it's a permissions problem, or some other mail
-server configuration problem is to cat an email-formatted text file
-directly to the roundup-mailgw script as the roundup user.::
-
- cat issue.txt | /usr/local/bin/roundup-mailgw /home/roundup
-
-If that doesn't raise any errors, the problem is the permissions of the
-MTA.
-
-----------------
Back to `Table of Contents`_
diff --git a/doc/customizing.txt b/doc/customizing.txt
index 076e9ceb09611898b0c7f396978671df2533b2a3..03060b7d7d90e03ab0121bdf6aeae6f0bcb6445d 100644 (file)
--- a/doc/customizing.txt
+++ b/doc/customizing.txt
Customising Roundup
===================
-:Version: $Revision: 1.22 $
+:Version: $Revision: 1.23 $
.. This document borrows from the ZopeBook section on ZPT. The original is at:
http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
Customisation of Roundup can take one of five forms:
-1. `instance configuration`_ file changes
-2. database, or `instance schema`_ changes
+1. `tracker configuration`_ file changes
+2. database, or `tracker schema`_ changes
3. "definition" class `database content`_ changes
4. behavioural changes, through detectors_
5. `access controls`_
The third case is special because it takes two distinctly different forms
-depending upon whether the instance has been initialised or not. The other two
-may be done at any time, before or after instance initialisation. Yes, this
+depending upon whether the tracker has been initialised or not. The other two
+may be done at any time, before or after tracker initialisation. Yes, this
includes adding or removing properties from classes.
-Instances in a Nutshell
------------------------
+Trackers in a Nutshell
+----------------------
-Instances have the following structure:
+Trackers have the following structure:
+-------------------+--------------------------------------------------------+
-|instance_config.py |Holds the basic instance_configuration |
+|config.py |Holds the basic `tracker configuration`_ |
+-------------------+--------------------------------------------------------+
-|dbinit.py |Holds the instance_schema |
+|dbinit.py |Holds the `tracker schema`_ |
+-------------------+--------------------------------------------------------+
-|interfaces.py |Defines the Web and E-Mail interfaces for the instance |
+|interfaces.py |Defines the Web and E-Mail interfaces for the tracker |
+-------------------+--------------------------------------------------------+
-|select_db.py |Selects the database back-end for the instance |
+|select_db.py |Selects the database back-end for the tracker |
+-------------------+--------------------------------------------------------+
-|db/ |Holds the instance's database |
+|db/ |Holds the tracker's database |
+-------------------+--------------------------------------------------------+
-|db/files/ |Holds the instance's upload files and messages |
+|db/files/ |Holds the tracker's upload files and messages |
+-------------------+--------------------------------------------------------+
-|detectors/ |Auditors and reactors for this instance |
+|detectors/ |Auditors and reactors for this tracker |
+-------------------+--------------------------------------------------------+
|html/ |Web interface templates, images and style sheets |
+-------------------+--------------------------------------------------------+
-Instance Configuration
-----------------------
+Tracker Configuration
+---------------------
-The instance_config.py located in your instance home contains the basic
+The config.py located in your tracker home contains the basic
configuration for the web and e-mail components of roundup's interfaces. This
file is a Python module. The configuration variables available are:
**INSTANCE_HOME** - ``os.path.split(__file__)[0]``
- The instance home directory. The above default code will automatically
- determine the instance home for you.
+ The tracker home directory. The above default code will automatically
+ determine the tracker home for you.
**MAILHOST** - ``'localhost'``
The SMTP mail host that roundup will use to send e-mail.
**DATABASE** - ``os.path.join(INSTANCE_HOME, 'db')``
This is the directory that the database is going to be stored in. By default
- it is in the instance home.
+ it is in the tracker home.
**TEMPLATES** - ``os.path.join(INSTANCE_HOME, 'html')``
This is the directory that the HTML templates reside in. By default they are
- in the instance home.
+ in the tracker home.
**INSTANCE_NAME** - ``'Roundup issue tracker'``
- A descriptive name for your roundup instance. This is sent out in e-mails and
+ A descriptive name for your roundup tracker. This is sent out in e-mails and
appears in the heading of CGI pages.
**ISSUE_TRACKER_EMAIL** - ``'issue_tracker@%s'%MAIL_DOMAIN``
The email address that e-mail sent to roundup should go to. Think of it as the
- instance's personal e-mail address.
+ tracker's personal e-mail address.
**ISSUE_TRACKER_WEB** - ``'http://your.tracker.url.example/'``
- The web address that the instance is viewable at. This will be included in
+ The web address that the tracker is viewable at. This will be included in
information sent to users of the tracker.
**ADMIN_EMAIL** - ``'roundup-admin@%s'%MAIL_DOMAIN``
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 node properties given by propname must have.
+ 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::
},
**HEADER_ADD_LINKS** - ``['issue']``
- List the classes that users are able to add nodes to.
+ List the classes that users are able to add items to.
**HEADER_SEARCH_LINKS** - ``['issue']``
List the classes that users can search.
Selects which props should be displayed on the filter page. Default is
all.
-The default instance_config.py is given below - as you
+The default config.py is given below - as you
can see, the MAIL_DOMAIN must be edited before any interaction with the
-instance is attempted.::
+tracker is attempted.::
# roundup home is this package's directory
INSTANCE_HOME=os.path.split(__file__)[0]
# This is the directory that the HTML templates reside in
TEMPLATES = os.path.join(INSTANCE_HOME, 'html')
- # A descriptive name for your roundup instance
+ # A descriptive name for your roundup tracker
INSTANCE_NAME = 'Roundup issue tracker'
# The email address that mail to roundup should go to
ISSUE_TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
- # The web address that the instance is viewable at
+ # The web address that the tracker is viewable at
ISSUE_TRACKER_WEB = 'http://your.tracker.url.example/'
# The email address that roundup will complain to if it runs into trouble
MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default
#MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out)
-Instance Schema
----------------
+Tracker Schema
+--------------
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.
-An instance schema defines what data is stored in the instance's database. The
+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::
organisation=String())
user.setkey("username")
user.create(username="admin", password=adminpw,
- address=instance_config.ADMIN_EMAIL)
+ address=config.ADMIN_EMAIL)
msg = FileClass(db, "msg", author=Link("user"), recipients=Multilink
("user"), date=Date(), summary=String(), files=Multilink("file"))
Classes and Properties - creating a new information store
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In the instance above, we've defined 7 classes of information:
+In the tracker above, we've defined 7 classes of information:
priority
Defines the possible levels of urgency for issues.
A Class defines a particular class (or type) of data that will be stored in the
database. A class comprises one or more properties, which given the information
-about the class nodes.
+about the class items.
The actual data entered into the database, using class.create() are called
-nodes. They have a special immutable property called id. We sometimes refer to
-this as the nodeid.
+items. They have a special immutable property called id. We sometimes refer to
+this as the itemid.
Properties
::::::::::
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 node selected from a specified
+ * 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.
- * A Multilink property refers to possibly many nodes in a specified class.
+ of the chosen item.
+ * A Multilink property refers to possibly many items in a specified class.
The value is a list of integers.
FileClass
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.
+directory of the db directory in your tracker.
IssueClass
::::::::::
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 node was created, and
-the value of the "activity" property is the date when any property on the node
+The value of the "creation" property is the date when a 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 node's journal). The "creator" property holds a link to the user
+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 nodes in the class by the content
+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
create(information)
:::::::::::::::::::
-Create a node in the database. This is generally used to create nodes in the
+Create a item in the database. This is generally used to create items in the
"definitional" classes like "priority" and "status".
--------------------------------------------
.. _detectors:
-The detectors in your instance fire before (*auditors*) and after (*reactors*)
+The detectors in your tracker fire before (*auditors*) and after (*reactors*)
changes to the contents of your database. They are Python modules that sit in
-your instance's ``detectors`` directory. You will have some installed by
+your tracker's ``detectors`` directory. You will have some installed by
default - have a look. You can write new detectors or modify the existing
ones. The existing detectors installed for you are:
This provides the ``chatty`` auditor which changes the issue status from
``unread`` or ``closed`` to ``chatting`` if new messages appear. It also
provides the ``presetunread`` auditor which pre-sets the status to
- ``unread`` on new nodes if the status isn't explicitly defined.
+ ``unread`` on new items if the status isn't explicitly defined.
See the detectors section in the `design document`__ for details of the
interface for detectors.
----------------
Note: if you modify the content of definitional classes, you'll most likely
- need to edit the instance `detectors`_ to reflect your changes.
+ need to edit the tracker `detectors`_ to reflect your changes.
Customisation of the special "definitional" classes (eg. status, priority,
-resolution, ...) may be done either before or after the instance is
+resolution, ...) may be done either before or after the tracker is
initialised. The actual method of doing so is completely different in each
case though, so be careful to use the right one.
-**Changing content before instance initialisation**
- Edit the dbinit module in your instance to alter the nodes created in using
+**Changing content before tracker initialisation**
+ Edit the dbinit module in your tracker to alter the items created in using
the create() methods.
-**Changing content after instance initialisation**
+**Changing content after tracker initialisation**
Use the roundup-admin interface's create, set and retire methods to add,
- alter or remove nodes from the classes in question.
+ alter or remove items from the classes in question.
-------------
The web interface works behind the cgi-bin/roundup.cgi or roundup-server
-scripts. In both cases, the scripts determine which instance is being accessed
+scripts. In both cases, the scripts 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 instance interfaces.Client class which handles the rest of
+control on to the tracker interfaces.Client class 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 instance.
+anything you want as a web interface to your tracker.
Figuring out what is displayed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Most customisation of the web view can be done by modifying the templates in
-the instance **html** directory. There are several types of files in there:
+the tracker **html** directory. There are several types of files in there:
page
defines the overall look of your tracker. When you
~~~~~~~~~~~~~~~~~~~~~~~
To determine the "context" of a request, we look at the URL and the special
-request variable ``:template``. The URL path after the instance identifier
+request variable ``:template``. The URL path after the tracker identifier
is examined. Typical URL paths look like:
1. ``/tracker/issue``
4. ``/cgi-bin/roundup.cgi/tracker/file1``
5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
-where the "instance identifier" is "tracker" in the above cases. That means
+where the "tracker identifier" is "tracker" in the above cases. That means
we're looking at "issue", "issue1", "_file/style.css", "file1" and
"file1/kitten.png" in the cases above. The path is generally only one
entry long - longer paths are handled differently.
b. if the path starts with "_file" (as in example 3,
"/tracker/_file/style.css"), then the additional path entry,
"style.css" specifies the filename of a static file we're to serve up
- from the instance "html" directory. Raises a SendStaticFile
+ from the tracker "html" directory. Raises a SendStaticFile
exception.
c. if there is something in the path (as in example 1, "issue"), it identifies
the tracker class we're to display.
elements you may use:
:link=designator:property and :multilink=designator:property
- The value specifies a node designator and the property on that
- node to add _this_ node to as a link or multilink.
- __note
- Create a message and attach it to the current node's
+ The value specifies an item designator and the property on that
+ item to add _this_ item to as a link or multilink.
+ :note
+ Create a message and attach it to the current item's
"messages" property.
- __file
- Create a file and attach it to the current node's
+ :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.
:required=property,property,...
Each of the actions is implemented by a corresponding *actionAction* (where
"action" is the name of the action) method on
-the roundup.cgi.Client class, which also happens to be in your instance as
+the roundup.cgi.Client class, which also happens to be in your tracker as
interfaces.Client. So if you need to define new actions, you may add them
there (see `definining new web actions`_).
Base behaviour is to check the user can view this class.
-Repurcussions of changing the instance schema
+Repurcussions of changing the tracker schema
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you choose to change the `instance schema`_ you will need to ensure the web
+If you choose to change the `tracker schema`_ you will need to ensure the web
interface knows about it:
1. Index, item and search pages for the relevant classes may need to have
Overall Look - "page" template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The "page" template in your instances
-roundup.cgi_client.Class. This class is mixed-in to your instance through the
-instance's interfaces module. This means you can override the header and
-footer with your own code. This allows you to use a sidebar navigation scheme,
-for example.
-
+XXX
How the templates work
~~~~~~~~~~~~~~~~~~~~~~
- the current index information (``filterspec``, ``filter`` args,
``properties``, etc) parsed out of the form.
- methods for easy filterspec link generation
- - *user*, the current user node as an HTMLItem instance
+ - *user*, the current user item as an HTMLItem instance
- *form*
The current CGI form information as a mapping of form argument
name to value
-*instance*
- The current instance
+*tracker*
+ The current tracker
*db*
The current database, through which db.config may be reached.
*nothing*
form the CGI form as a cgi.FieldStorage
env the CGI environment variables
url the current URL path for this request
-base the base URL for this instance
+base the base URL for this tracker
user a HTMLUser instance for this user
classname the current classname (possibly None)
template the current template (suffix, also possibly None)
The index view is determined by two parts of the 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
+with colons, and it determines the way that the properties of selected items
are displayed. The filter part consists of all the other query parameters, and
-it determines the criteria by which nodes are selected for display.
+it determines the criteria by which items are selected for display.
The filter part is interactively manipulated with the form widgets displayed in
the filter section. The layout part is interactively manipulated by clicking on
the column headings in the table.
specified Link properties and the intersection of the sets of items with values
matching any specified Multilink properties.
-The example specifies an index of "issue" nodes. Only items with a "status" of
+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 "security" and "ui" are displayed. The items
are grouped by priority, arranged in ascending order; and within groups, sorted
<tr>
<th nowrap>Change Note</th>
<td colspan=3>
- <textarea name="__note" wrap="hard" rows="5" cols="60"></textarea>
+ <textarea name=":note" wrap="hard" rows="5" cols="60"></textarea>
</td>
</tr>
<tr>
<th nowrap>File</th>
- <td colspan=3><input type="file" name="__file" size="40"></td>
+ <td colspan=3><input type="file" name=":file" size="40"></td>
</tr>
<tr>
When a change is submitted, the system automatically generates a message
describing the changed properties. As shown in the example, the editor
-template can use the "__note" and "__file" fields, which are added to the
+template can use the ":note" and ":file" fields, which are added to the
standard change note message generated by Roundup.
Spool Section
*To be done:*
-*The actual history entries of the node may be accessed for manual templating
+*The actual history entries of the item may be accessed for manual templating
through the "journal" method of the item*::
<tal:block tal:repeat="entry context/journal">
@@ -1160,18 +1155,18 @@ email users get, for example to not give them access to the web interface if
they register through email.
You may use the ``roundup-admin`` "``security``" command to display the
-current Role and Permission configuration in your instance.
+current Role and Permission configuration in your tracker.
Adding a new Permission
~~~~~~~~~~~~~~~~~~~~~~~
When adding a new Permission, you will need to:
-1. add it to your instance's dbinit so it is created
+1. add it to your tracker's dbinit so it is created
2. enable it for the Roles that should have it (verify with
"``roundup-admin security``")
3. add it to the relevant HTML interface templates
-4. add it to the appropriate xxxPermission methods on in your instance
+4. add it to the appropriate xxxPermission methods on in your tracker
interfaces module
diff --git a/doc/design.txt b/doc/design.txt
index 1c7de7b144335cf4bd5739333372c7ad1f7e9aca..27a29646db42e3247b96030831d315e6193a550d 100644 (file)
--- a/doc/design.txt
+++ b/doc/design.txt
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
Nodes 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.
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
+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
conventionally enclosed in square brackets when mentioned
in plain text. This permits a casual mention of, say,
- Date properties store date-and-time stamps.
Their values are Timestamp objects.
-- A Link property refers to a single other node
+- 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.
-- A Multilink property refers to possibly many nodes
+- A Multilink property refers to possibly many items
in a specified class. The value is a list of integers.
*None* is also a permitted value for any of these property
class Link:
def __init__(self, classname, do_journal='yes'):
"""An object designating a Link property that links to
- nodes in a specified class.
+ items in a specified class.
If the do_journal argument is not 'yes' then changes to
- the property are not journalled in the linked node.
+ the property are not journalled in the linked item.
"""
class Multilink:
def __init__(self, classname, do_journal='yes'):
"""An object designating a Multilink property that links
- to nodes in a specified class.
+ to items in a specified class.
If the do_journal argument is not 'yes' then changes to
- the property are not journalled in the linked node(s).
+ the property are not journalled in the linked item(s).
"""
"""
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.
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
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
'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 the given nodes.
+ def find(self, propname, itemid):
+ """Get the ids of items in this class which link to the given items.
- 'propspec' consists of keyword args propname={nodeid:1,}
+ 'propspec' consists of keyword args propname={itemid:1,}
'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.
- Any node in this class whose 'propname' property links to any of the
- nodeids will be returned. Used by the full text indexing, which
+ Any item in this class whose 'propname' property links to any of the
+ itemids will be returned. Used by the full text indexing, which
knows that "foo" occurs in msg1, msg3 and file7, so we have hits
on these issues:
"""
def filter(self, search_matches, filterspec, sort, group):
- ''' Return a list of the ids of the active nodes in this class that
+ ''' Return a list of the ids of the active items in this class that
match the 'filter' spec, sorted by the group spec and then the
sort spec.
'''
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:
is raised before any properties have been added.
"""
- def getnode(self, nodeid, cache=1):
- ''' Return a Node convenience wrapper for the node.
+ def getitem(self, itemid, cache=1):
+ ''' Return a Node convenience wrapper for the 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.
'cache' indicates whether the transaction cache should be queried
- for the node. If the node has been modified and you need to
+ for the item. If the item has been modified and you need to
determine what its values prior to modification are, you need to
set cache=0.
'''
class Node:
- ''' A convenience wrapper for the given node. It provides a mapping
- interface to a single node's properties
+ ''' A convenience wrapper for the given item. It provides a mapping
+ interface to a single item's properties
'''
Hyperdatabase Implementations
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.
Roundup Database
hyperdatabase and mediates calls to the database.
Some of the classes in the Roundup database are considered
issue classes.
-The Roundup database layer adds detectors and user nodes,
+The Roundup database layer adds detectors and user items,
and on issues it provides mail spools, nosy lists, and superseders.
Reserved Classes
~~~~~~~~~~~~~~~~
Internal to this layer we reserve three special classes
-of nodes that are not issues.
+of items that are not issues.
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::
hyperdb.Class(db, "user", username=hyperdb.String(),
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::
hyperdb.Class(db, "msg", author=hyperdb.Link("user"),
files=hyperdb.Multilink("file"))
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.
"""""
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::
hyperdb.Class(db, "file", user=hyperdb.Link("user"),
class Database:
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:
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.
"""
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 issue'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 issue.
"""
- def sendmessage(self, nodeid, msgid):
+ def sendmessage(self, itemid, msgid):
"""Send a message to the members of an issue's nosy list.
The message is sent only to users on the nosy list who are not
There are two kinds of detectors:
-1. an auditor is triggered just before modifying an node
-2. a reactor is triggered just after an node has been modified
+1. an auditor is triggered just before modifying an item
+2. a reactor is triggered just after an item has been modified
When the Roundup database is about to perform a
``create()``, ``set()``, or ``retire()``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``audit()`` and ``react()`` methods
-register detectors on a given class of nodes::
+register detectors on a given class of items::
class Class:
def audit(self, event, detector):
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 IssueClass 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
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 IssueClass 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.
Detector Example
~~~~~~~~~~~~~~~~
db.project.react("set", approve_project)
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
time zone, and accepted in the full format or any of the partial
formats explained above.
-- Link values are printed as node designators. When given as
- an argument, node designators and key strings are both accepted.
+- Link values are printed as item designators. When given as
+ an argument, item designators and key strings are both accepted.
-- 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.
+- 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
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
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
subject line (after skipping any "Fwd:" or "Re:" prefixes).
If an issue designator (class name and id number) is found
-there, the newly created "msg" node is added to the "messages"
-property for that issue, and any new "file" nodes are added to
+there, the newly created "msg" item is added to the "messages"
+property for that issue, and any new "file" items are added to
the "files" property for the issue.
If just an issue class name is found there, we attempt to
create a new issue 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
issue'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.
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
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)
field display a property like the
plain displayer above, but in a text field
menu for a Link property, display
a menu of the available choices
link for a Link or Multilink property,
- display the names of the linked nodes, hyperlinked to the
- issue views on those nodes
+ display the names of the linked items, hyperlinked to the
+ issue views on those items
count for a Multilink property, display
a count of the number of links in the list
reldate display a Date property in terms
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
of issues with values matching any specified Multilink
properties.
-The example specifies an index of "issue" nodes.
+The example specifies an index of "issue" items.
Only issues with a "status" of either
"unread" or "in-progres" or "resolved" are displayed,
and only issues with "topic" values including both
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.
Issue Views
The spool section lists messages in the issue'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.
Access Control
application initialises.
There will be two levels of Permission. The Class level permissions define
-logical permissions associated with all nodes of a particular class (or all
+logical permissions associated with all items of a particular class (or all
classes). The Node level permissions define logical permissions associated
-with specific nodes by way of their user-linked properties.
+with specific items by way of their user-linked properties.
Access Control Interface Specification
"permission" is there for the specified classname.
'''
- def hasNodePermission(self, classname, nodeid, **propspec):
- ''' Check the named properties of the given node to see if the
+ def hasNodePermission(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.
'propspec' consists of a set of properties and values that
- must be present on the given node for access to be granted.
+ must be present on the given item for access to be granted.
If a property is a Link, the value must match the property
value. If a property is a Multilink, the value must appear
p = db.security.addPermission(name="May Resolve", klass="issue")
security.addToRole('Manager', p)
-The instance dbinit module then has in ``open()``::
+The tracker dbinit module then has in ``open()``::
# open the database - it must be modified to init the Security class
# from security.py as db.security
- db = Database(instance_config, name)
+ db = Database(config, name)
# add some extra permissions and associate them with roles
ei = db.security.addPermission(name="Edit", klass="issue",
# create the two default users
user.create(username="admin", password=Password(adminpw),
- address=instance_config.ADMIN_EMAIL, roles='Admin')
+ address=config.ADMIN_EMAIL, roles='Admin')
user.create(username="anonymous", roles='Anonymous')
Then in the code that matters, calls to ``hasPermission`` and
if db.security.hasPermission('issue', 'Edit', userid):
# all ok
- if db.security.hasNodePermission('issue', nodeid, assignedto=userid):
+ if db.security.hasNodePermission('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 node using ``hasNodePermission``. If
+- the other attributes are lookups on the item using ``hasNodePermission``. 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
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/developers.txt b/doc/developers.txt
index 3e51a09266eed669486fc8b90ea3b05c8f84ae09..620d9a6eaa142c4d19c552bf1fb594256d8abf28 100644 (file)
--- a/doc/developers.txt
+++ b/doc/developers.txt
Developing Roundup
==================
-:Version: $Revision: 1.3 $
+:Version: $Revision: 1.4 $
Note: the intended audience of this document is the developers of the core
Roundup code. If you just wish to alter some behaviour of your Roundup
Other project rules:
- New functionality must be documented, even briefly (so at least we know
- where there's missing documentation) and changes to instance configuration
+ where there's missing documentation) and changes to tracker configuration
must be logged in the upgrading document.
- subscribe to roundup-checkins to receive checkin notifications from the
other developers with CVS access
index 15a6c249cbb2392800f1398c22b1d3eef26916a8..d58bbea74b4c1fece22cdca5ccb527867c083017 100644 (file)
--- a/doc/getting_started.txt
+++ b/doc/getting_started.txt
Getting Started
===============
-:Version: $Revision: 1.5 $
+:Version: $Revision: 1.6 $
.. contents::
"``PYTHONPATH=. python roundup/scripts/roundup_server.py``" for
``roundup-server``.
-The Instance
-------------
+The Tracker
+-----------
-We'll be referring to the term instance a lot from now on. An instance is a
+We'll be referring to the term tracker a lot from now on. A tracker 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
Database schema
This describes the content of the hyperdatabase - what fields are stored
- for issues, what user information, etc. Being stored in the instance,
+ for issues, what user information, etc. Being stored in the tracker,
this allows it to be customised for a particular application. It also
means that changes in the Roundup core code do not affect a running
- instance.
+ tracker.
Web Interface
- The web interface templates are defined in the instance too - and the
+ The web interface templates are defined in the tracker too - and the
actual CGI interface class is defined (mostly using base classes in the
Roundup core code) so it, like the database, may be customised for each
- instance in use.
+ tracker in use.
-Instances are created using the ``roundup-admin`` tool.
+Trackers are created using the ``roundup-admin`` tool.
Command Line Tool
-----------------
-To set up a new instance, run "``roundup-admin install``". You will be
+To set up a new tracker, run "``roundup-admin install``". You will be
asked a few questions:
-1. Instance home directory
+1. Tracker home directory
2. Schema to use
3. Database back-end to use
-Once you've chosen these, roundup will install the instance for you. It will
+Once you've chosen these, roundup will install the tracker for you. It will
then indicate that you should configure some more information in the
-file "``instance_config.py``" in the instance home. It
+file "``config.py``" in the tracker home. It
should be edited before roundup is initialised, and may have the following
variable declarations:
You may also alter the default schema - see the `customisation`_ documentation
for more info on both configuration variables and schema modifications.
-Once you're happy (and note that you can change any of this after the instance
+Once you're happy (and note that you can change any of this after the tracker
is initialised too!) you must run "``roundup-admin initialise``".
You should also think about whether there is going to be controlled access
to the
-instance on the machine the instance is running on. That is, who can
+tracker on the machine the tracker is running on. That is, who can
actually make
changes to the database using the roundup-admin tool. See the section on
-Users_and_Access_Control for information on how to secure your instance from the
+Users_and_Access_Control for information on how to secure your tracker from the
start.
E-Mail Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set up a mail alias called "issue_tracker" as (include the quote marks):
-"``|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_home>``"
+"``|/usr/bin/python /usr/local/bin/roundup-mailgw <tracker_home>``"
In some installations (e.g. RedHat 6.2 I think) you'll need to set up smrsh so
sendmail will accept the pipe command. In that case, symlink
``/etc/smrsh/roundup-mailgw`` to "``/usr/local/bin/roundup-mailgw``" and change
the command to::
- |roundup-mailgw <instance_home>
+ |roundup-mailgw <tracker_home>
To test the mail gateway on unix systems, try::
Set ``roundup-mailgw`` up to run every 10 minutes or so. For example::
- 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> mailbox <mail_spool_file>
+ 10 * * * * /usr/local/bin/roundup-mailgw <tracker_home> mailbox <mail_spool_file>
Where the ``mail_spool_file`` argument is the location of the roundup submission
user's mail spool. On most systems, the spool for a user "issue_tracker"
To retrieve from a POP mailbox, use a similar cron entry to the mailbox one::
- 10 * * * * /usr/local/bin/roundup-mailgw <instance_home> pop <pop_spec>
+ 10 * * * * /usr/local/bin/roundup-mailgw <tracker_home> pop <pop_spec>
where pop_spec is "``username:password@server``" that specifies the roundup
submission user's POP account name, password and server.
Stand-alone:
1. Edit roundup-server at the top - ``ROUNDUP_INSTANCE_HOMES`` needs to know
- about your instance. You may also specify the values for
+ about your tracker. You may also specify the values for
``ROUNDUP_INSTANCE_HOMES`` on the command-line using "name=home" pairs.
- 2. "``roundup-server [-p port] (name=instance_home)*``" (hostname may be "")
+ 2. "``roundup-server [-p port] (name=tracker_home)*``" (hostname may be "")
- 3. Load up the page "``/<instance name>/index``" where instance name is the name
+ 3. Load up the page "``/<tracker name>/index``" where tracker name is the name
you nominated in ``ROUNDUP_INSTANCE_HOMES``.
Apache:
distribution.
2. Make sure roundup.cgi is executable. Edit it at the top -
- ``ROUNDUP_INSTANCE_HOMES`` needs to know about your instance.
+ ``ROUNDUP_INSTANCE_HOMES`` needs to know about your tracker.
3. Edit your "``/etc/httpd/conf/httpd.conf``" and make sure that the
"``/home/httpd/html/roundup/roundup.cgi``" script will be treated as a CGI script.
4. Re-start your apache to re-load the config if necessary.
- 5. Load up the page "``/roundup/roundup.cgi/index/``" where instance name is the
+ 5. Load up the page "``/roundup/roundup.cgi/index/``" where tracker name is the
name you nominated in ``ROUNDUP_INSTANCE_HOMES``.
6. To use the CGI script unchanged, which allows much easier updates, add
these directives to your "httpd.conf"::
SetEnv ROUNDUP_LOG "/var/log/roundup.log"
- SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/instances/Default"
+ SetEnv ROUNDUP_INSTANCE_HOMES "Default=/usr/local/share/roundup/trackers/Default"
SetEnv ROUNDUP_DEBUG "0"
7. On Windows, write a batch file "roundup.bat" similar to the one below and
@echo off
set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
- set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default;
+ set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\trackers\Default;
set ROUNDUP_DEBUG=0
c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi
Users and permissions
~~~~~~~~~~~~~~~~~~~~~
-By default, roundup automatically creates one user when the instance database is
+By default, roundup automatically creates one user when the tracker database is
initialised (using roundup-admin init). The user is "admin" and the password is
the one you supply at that time.
1. Add a new user and group to your system (e.g. "issue_tracker")
- 2. When creating a new instance home, use the following commands
- (substituting instance_home for the directory you want to use)::
+ 2. When creating a new tracker home, use the following commands
+ (substituting tracker_home for the directory you want to use)::
- mkdir instance_home
- chown issue_tracker:issue_tracker instance_home
- chmod g+rwxs instance_home
- roundup-admin -i instance_home init
+ mkdir tracker_home
+ chown issue_tracker:issue_tracker tracker_home
+ chmod g+rwxs tracker_home
+ roundup-admin -i tracker_home init
3. Now, edit the /etc/group line for the issue_tracker group so it
includes the unix logins of all the users who are going to
- administer your roundup instance. If you're running the web or mail
+ administer your roundup tracker. If you're running the web or mail
gateways, then be sure to include those users in the group too (on
some Linux systems, these users are "www" or "apache" and "mail".)
To add users, use one of the following interfaces:
-1. On the web, access the URL .../<instance name>/newuser to bring up a form
+1. On the web, access the URL .../<tracker name>/newuser to bring up a form
which may be used to add a new user.
2. On the command-line, use::
- roundup-admin -i <instance home> create user username=bozo password=bozo
+ roundup-admin -i <tracker home> create user username=bozo password=bozo
address=richard@clown.org
Supply the admin username and password. roundup-admin will print the id
To add issues, use one of the following interfaces:
-1. On the web, access the URL .../<instance name>/newissue to bring up a
+1. On the web, access the URL .../<tracker name>/newissue to bring up a
form which may be used to add a new issue.
2. On the command-line, use::
- roundup-admin -i <instance home> create issue title="test issue"
+ roundup-admin -i <tracker home> create issue title="test issue"
Supply the admin username and password. roundup-admin will print the id
of the new issue.
diff --git a/doc/glossary.txt b/doc/glossary.txt
index 001470f9ae156969bf35222821a7486c519fa044..b0ed7aea6f49e292e958ab78af4405882fef0e5c 100644 (file)
--- a/doc/glossary.txt
+++ b/doc/glossary.txt
Roundup Glossary
================
-:Version: $Revision: 1.2 $
+:Version: $Revision: 1.3 $
.. contents::
class
- a definition of the properties and behaviour of a set of nodes
+ a definition of the properties and behaviour of a set of items
db
- a collection of nodes
+ a collection of items
designator
- a combined class + nodeid reference to any node in the hyperdb
-nodeid
- a numeric reference to a particular node of one class
-node
+ a combined class + itemid reference to any item in the hyperdb
+itemid
+ a numeric reference to a particular item of one class
+item
a collection of data that forms one entry in the hyperdb.
property
- one element of data that makes up a node
+ one element of data that makes up an item
schema
- the definition of all the classes that make up an instance
-instance
+ the definition of all the classes that make up an tracker
+tracker
I've defined this well somewhere else...
diff --git a/doc/implementation.txt b/doc/implementation.txt
index 168222429ac8768efba95d4ff2d4647465a935e4..520f454a62d6846894cf7c5fe643a6ec2deb4d66 100644 (file)
--- a/doc/implementation.txt
+++ b/doc/implementation.txt
Implementation notes
====================
-:Version: $Revision: 1.4 $
+:Version: $Revision: 1.5 $
[see also the roundup package docstring]
pass on to the templating mechanism, but the file class _always_ does
downloading. It'll probably stay this way too...
- template - call="link(property)" may be used to link "the current node"
+ template - call="link(property)" may be used to link "the current item"
(from an index) - the link text is the property specified.
template - added functions that I found very useful: List, History and
diff --git a/doc/installation.txt b/doc/installation.txt
index 00a29c0431e85233af6a948f6dc4e3821b6d8dd4..b9f05ad29e895ee5673f4b1f53f108c7d3877188 100644 (file)
--- a/doc/installation.txt
+++ b/doc/installation.txt
Installing Roundup
==================
-:Version: $Revision: 1.21 $
+:Version: $Revision: 1.22 $
.. contents::
These include the email gateway, the roundup
HTTP server, the roundup administration command-line interface, etc.
-Roundup instances
- Instances consist of core support files, issues
- (be they bug reports or otherwise), instance configuration file(s),
- etc. Roundup instances also adhere to a specific "Template" which
+Roundup trackers
+ Trackers consist of core support files, issues
+ (be they bug reports or otherwise), tracker configuration file(s),
+ etc. Roundup trackers also adhere to a specific "Template" which
defines the fields usable/assignable on a per-issue basis. A
description of the provided templates follows.
"usability" and "feature".
Users of this template will want to change the contents of the product
-class as soon as the instance is created.
+class as soon as the tracker is created.
Prerequisites
Basic Installation Steps
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
1. To install the Roundup support code into your Python tree and
Roundup scripts into /usr/local/bin::
python setup.py install --install-scripts=/opt/roundup/bin
-2. To create a Roundup instance (necessary to do before you can
+2. To create a Roundup tracker (necessary to do before you can
use the software in any real fashion):
- a. (Optional) If you intend to keep your roundup instances
+ a. (Optional) If you intend to keep your roundup trackers
under one top level directory which does not exist yet,
you should create that directory now. Example:
- mkdir /opt/roundup/instances
+ mkdir /opt/roundup/trackers
b. Either add the Roundup script location to your ``PATH``
environment variable or specify the full path to
You will be asked a series of questions. A description of
the Roundup-provided templates can be found under the Overview_::
- Enter instance home: /opt/roundup/instances/support
+ Enter tracker home: /opt/roundup/trackers/support
Templates: classic, extended
Select template [classic]: classic
Back ends: anydbm, bsddb
Select backend [anydbm]: anydbm
- You will now be directed to edit the instance configuration and
+ You will now be directed to edit the tracker configuration and
initial schema. See `Customising Roundup`_ for details on configuration
and schema changes. Note that you may change any of the configuration
- after you've initialised the instance - it's just better to have valid
+ after you've initialised the tracker - it's just better to have valid
values for this stuff now.
d. ``roundup-admin initialise``
- This step initialises the instance database. You will need to supply
+ This step initialises the tracker database. You will need to supply
an admin password at this step. You will be prompted::
Admin Password:
Confirm:
- Once this is done, the instance has been created.
+ Once this is done, the tracker has been created.
3. XXX Set up the CGI interface
Shared Environment Steps
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
-Each instance ideally should have its own UNIX group, so create
+Each tracker ideally should have its own UNIX group, so create
a UNIX group (edit ``/etc/group`` or your appropriate NIS map if
you're using NIS). To continue with my examples so far, I would
create the UNIX group 'support', although the name of the UNIX
-group does not have to be the same as the instance name. To this
+group does not have to be the same as the tracker name. To this
'support' group I then add all of the UNIX usernames who will be
-working with this Roundup instance. In addition to 'real' users,
+working with this Roundup tracker. In addition to 'real' users,
the Roundup email gateway will need to have permissions to this
area as well, so add the user your mail service runs as to the
group. The UNIX group might then look like::
support:*:1002:jblaine,samh,geezer,mail,apache
-The instance "db" directory should be chmod'ed g+sw so that the group can
+The tracker "db" directory should be chmod'ed g+sw so that the group can
write to the database, and any new files created in the database will be owned
by the group.
may actually login and play with the roundup setup.
Internet Setup
-~~~~~~~~~~~~~~
+--------------
1. There are two supported ways to get emailed issues into the
- Roundup instance. You should pick ONE of the following, both
+ Roundup tracker. You should pick ONE of the following, both
of which will continue my example setup from above:
a. Set up a mail alias called "support" as::
- "|/opt/roundup/bin/roundup-mailgw /opt/roundup/instances/support"
+ "|/opt/roundup/bin/roundup-mailgw /opt/roundup/trackers/support"
If you use Sendmail's ``smrsh`` mechanism, please read the notes
under 'Platform-Specific Notes'
line)::
10 * * * * /opt/roundup/bin/roundup-mailgw
- /opt/roundup/instances/support /var/mail/support
+ /opt/roundup/trackers/support /var/mail/support
If you don't want to use the email component of Roundup, then remove the
- "``nosyreator.py``" module from your instance "``detectors``" directory.
+ "``nosyreator.py``" module from your tracker "``detectors``" directory.
2. Test the email gateway. Under most flavors of UNIX, this
can be done by::
=========
Read the separate `upgrading document`_, which describes the steps needed to
-upgrade existing tracker instances for each version of Roundup that is
+upgrade existing tracker trackers for each version of Roundup that is
released.
your Products directory either in an INSTANCE_HOME/Products or the Zope
code tree lib/python/Products.
-You will need to create the instance using the roundup-admin tool (step 2 in
+You will need to create the tracker using the roundup-admin tool (step 2 in
installation_).
When you next (re)start up Zope, you will be able to add a ZRoundup object
-that interfaces to your new instance.
+that interfaces to your new tracker.
Further Reading
which points to the full path of your actual ``roundup-mailgw``
script.
-2. change your alias to ``"|roundup-mailgw <instance_home>"``
+2. change your alias to ``"|roundup-mailgw <tracker_home>"``
Linux
diff --git a/doc/security.txt b/doc/security.txt
index 93c64f9e852adddee22018f301bd9dc8b71fc6a7..10dedbab868494510de25ac9f981dd1d27ac26b4 100644 (file)
--- a/doc/security.txt
+++ b/doc/security.txt
Security Mechanisms
===================
-:Version: $Revision: 1.15 $
+:Version: $Revision: 1.16 $
Current situation
=================
Security controls in Roundup could be approached in three ways:
-1) at the hyperdb level, with read/write/modify permissions on classes, nodes
- and node properties for all or specific transitions.
+1) at the hyperdb level, with read/write/modify permissions on classes, items
+ and item properties for all or specific transitions.
2) at the user interface level, with access permissions on CGI interface
methods, mailgw methods, roundup-admin methods, and so on.
3) at a logical permission level, checked as needed.
---------------------
Control is implemented at the Class.get, Class.set and Class.create level. All
-other methods must access nodes through these methods. Since all accesses go
+other methods must access items through these methods. Since all accesses go
through the database, we can implement deny by default.
Pros:
- harder to determine the relationship between user interaction and hyperdb
permission.
- a lot of work to define
- - must special-case to handle by-node permissions (editing user details,
+ - must special-case to handle by-item permissions (editing user details,
having private messages)
diff --git a/doc/templating.txt b/doc/templating.txt
index e303a1a245e85e4805f8fa24a7c15fe57849aa8e..0a750d9ae9539d958dbd98ce1199dac8b8d17ac7 100644 (file)
--- a/doc/templating.txt
+++ b/doc/templating.txt
HTML Templating Mechanisms
==========================
-:Version: $Revision: 1.13 $
+:Version: $Revision: 1.14 $
Current Situation and Issues
============================
We should also take this opportunity to open up the flexibility of the
templates through:
-1. allowing the instance to define a "page" template, which holds the overall
+1. allowing the tracker to define a "page" template, which holds the overall
page structure, including header and footer
defined:
*klass*
- The current class of node being displayed as an HTMLClass instance. Name is
+ The current class of item being displayed as an HTMLClass instance. Name is
mangled so it can be used in Python expressions.
*item*
- The current node from the database, if we're viewing a specific node, as an
+ The current item from the database, if we're viewing a specific item, as an
HTMLItem instance. If it doesn't exist, then we're on a new item page.
(*classname*)
this is one of two things:
- 1. the *item* is also available under its classname, so a *user* node
+ 1. the *item* is also available under its classname, so a *user* item
would also be available under the name *user*. This is also an HTMLItem
instance.
2. if there's no *item* then the current class is available through this
- the current index information (``filterspec``, ``filter`` args,
``properties``, etc) parsed out of the form.
- methods for easy filterspec link generation
- - *user*, the current user node as an HTMLItem instance
+ - *user*, the current user item as an HTMLItem instance
-*instance*
- The current instance
+*tracker*
+ The current tracker
*db*
The current open database
of special template types:
[classname].index
- This template is used when the URL specifies only the class, and not a node
+ This template is used when the URL specifies only the class, and not an item
designator. It displays a list of [classname] items from the database, and
a "filter refinement" form.
Would perform a TAL ``repeat`` command using the list supplied by
diff --git a/doc/upgrading.txt b/doc/upgrading.txt
index 6620e6a111779f433ca4e50b2eb6b8e2a2c89c66..ce6ae6dfaa91843df66e4ec1df283eeefd269eb8 100644 (file)
--- a/doc/upgrading.txt
+++ b/doc/upgrading.txt
Upgrading to newer versions of Roundup
======================================
-Please read each section carefully and edit your instance home files
+Please read each section carefully and edit your tracker home files
accordingly.
.. contents::
define your own Permissions that may be checked in CGI transactions.
4. Journalling has been made less storage-hungry, so has been turned on
by default *except* for author, recipient and nosy link/unlink events. You
- are advised to turn it off in your instances too.
-5. Because of the above changes, the instance configuration has seen some
+ are advised to turn it off in your trackers too.
+5. We've changed the terminology from "instance" to "tracker", to ease the
+ learning curve/impact for new users.
+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
is as simple as copying the "db" directory and all its contents from your
-instance to somewhere safe.
+tracker to somewhere safe.
0.5.0 Configuration
-------------------
+First up, rename your ``instance_config.py`` file to just ``config.py``.
+
+Then edit your tracker's ``__init__.py`` module. It'll currently look
+like this::
+
+ from instance_config import *
+ try:
+ from dbinit import *
+ except ImportError:
+ pass # in installdir (probably :)
+ from interfaces import *
+
+and it needs to be::
+
+ import config
+ from dbinit import open, init
+ from interfaces import Client, MailGW
+
Due to the new templating having a top-level ``page`` that defines links for
searching, indexes, adding items etc, the following variables are no longer
used:
- ISSUE_FILTER
The new security implementation will require additions to the dbinit module,
-but also removes the need for the following instance config variables:
+but also removes the need for the following tracker config variables:
- ANONYMOUS_ACCESS
- ANONYMOUS_REGISTER
0.5.0 Database backend changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Your select_db module in your instance has changed a fair bit. Where it used
+Your select_db module in your tracker has changed a fair bit. Where it used
to contain::
# WARNING: DO NOT EDIT THIS FILE!!!
Yes, I realise the irony of the "DO NOT EDIT THIS FILE" statement :)
Note the addition of the Class, FileClass, IssueClass imports. These are very
important, as they're going to make the next change work too. You now need to
-modify the top of the dbinit module in your instance from::
+modify the top of the dbinit module in your tracker from::
import instance_config
from roundup import roundupdb
'''
pass
+to::
-
-to just::
-
- import instance_config
+ import config
from select_db import Database, Class, FileClass, IssueClass
Yes, remove the Database and IssueClass definitions and those other imports.
They're not needed any more!
+Look for places in dbinit.py where ``instance_config`` is used too, and
+rename them ``config``.
+
0.5.0 Journalling changes
~~~~~~~~~~~~~~~~~~~~~~~~~
4. Roundup checks that users have appropriate Permissions at appropriate times
(like editing issues).
-Your instance dbinit module's *open* function now has to define any
-Permissions that are specific to your instance, and also the assignment
+Your tracker dbinit module's *open* function now has to define any
+Permissions that are specific to your tracker, and also the assignment
of Permissions to Roles. At the moment, your open function
ends with::
and all other users "User". The ``fixroles.py`` script in the tools directory
will do this. Run it like so (where python is your python 2+ binary)::
- python tools/fixroles.py -i <instance home>
+ python tools/fixroles.py -i <tracker home>
---------------------------
The CGI interface code was completely reorganised and largely rewritten. The
-end result is that this section of your instance interfaces module will need
+end result is that this section of your tracker interfaces module will need
changing from::
from roundup import mailgw
0.5.0 HTML templating
---------------------
-You'll want to make a backup of your current instance html directory. You
+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 instance, and modify it according to your local schema
+used to create your tracker, and modify it according to your local schema
changes.
If you need help with the new templating system, please ask questions on the
0.5.0 Detectors
---------------
-The nosy reactor has been updated to handle the instance not having an
-"assignedto" property on issues. You may want to copy it into your instance's
+The nosy reactor has been updated to handle the tracker not having an
+"assignedto" property on issues. You may want to copy it into your tracker's
detectors directory. Chances are you've already fixed it though :)
0.4.2 HTML templating changes
-----------------------------
The link() htmltemplate function now has a "showid" option for links and
-multilinks. When true, it only displays the linked node id as the anchor
+multilinks. When true, it only displays the linked item id as the anchor
text. The link value is displayed as a tooltip using the title anchor
attribute. To use in eg. the superseder field, have something like this::
diff --git a/doc/user_guide.txt b/doc/user_guide.txt
index fed58e1aa7a0088193920a4de44ec883ff7b64bb..ed410575d2b200e2c46454e5e9e71bf49b92ace3 100644 (file)
--- a/doc/user_guide.txt
+++ b/doc/user_guide.txt
User Guide
==========
-:Version: $Revision: 1.5 $
+:Version: $Revision: 1.6 $
.. contents::
| :columns | selects the columns that should be displayed. |
| | Default is all. |
+-----------+--------------------------------------------------------------+
-| propname | selects the values the node properties given by propname |
+| propname | selects the values the item properties given by propname |
| | must have (very basic search/filter). |
+-----------+--------------------------------------------------------------+
stripped off the subject line before we start looking for real information.
If an item designator (class name and id number, for example ``issue123``)
-is found there, a new "msg" node is added to the "messages" property for
-that item, and any new "file" nodes are added to the "files" property for
+is found there, a new "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.
+item and its "files" property initialized to contain any new "file" items.
The third case above - where no ``[information]`` is provided, the tracker's
``MAIL_DEFAULT_CLASS`` configuration variable defines what class of item
* In a multipart/mixed message or part, each subpart is extracted and
examined. 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. Any parts of other types are each stored in separate files and
- given "file" class nodes that are linked to the "msg" node.
+ item. Any parts of other types are each stored in separate files and
+ given "file" class items that are linked to the "msg" item.
* In a multipart/alternative message or part, we look for a text/plain
subpart and ignore the other parts.
Message summary
:::::::::::::::
-The "summary" property on message nodes is taken from the first non-quoting
+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 with a ">" or
"|" character are considered "quoting sections". The first line of the first
message are
looked up among the tracker users, and the corresponding users are placed
in the
-"recipients" property on the new "msg" node. The address in the ``From:`` header
-similarly determines the "author" property of the new "msg" node. The default
+"recipients" property on the new "msg" item. The address in the ``From:`` header
+similarly determines the "author" property of the 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.
Command Line Tool
-----------------
-Usage: ``roundup-admin [-i instance home] [-u login] [-c] <command> <arguments>``
+Usage: ``roundup-admin [-i tracker home] [-u login] [-c] <command> <arguments>``
Options:
--i instance home specify the issue tracker "home directory" to administer
+-i tracker home specify the issue tracker "home directory" to administer
-u the ``user[:password]`` to use for commands
-c when outputting lists of data, comma-separate them
+-------------+---------------------------------------------------------------+
|display |Usage: display designator |
| |This lists the properties and their associated values for the |
-| |given node. |
+| |given item. |
+-------------+---------------------------------------------------------------+
|export |Usage: export class[,class] destination dir |
| |This action exports the current data from the database into |
| |directory. The journals are not exported. |
+-------------+---------------------------------------------------------------+
|find |Usage: find classname propname=value ... |
-| |Find the nodes of the given class with a given link property |
+| |Find the items of the given class with a given link property |
| |value. The |
-| |value may be either the nodeid of the linked node, or its key |
+| |value may be either the itemid of the linked item, or its key |
| |value. |
+-------------+---------------------------------------------------------------+
|get |Usage: get property designator[,designator]* |
-| |Retrieves the property value of the nodes specified by the |
+| |Retrieves the property value of the items specified by the |
| |designators. |
+-------------+---------------------------------------------------------------+
|help |Usage: help topic |
| |all -- all available help |
+-------------+---------------------------------------------------------------+
|history |Usage: history designator |
-| |Lists the journal entries for the node identified by the |
+| |Lists the journal entries for the item identified by the |
| |designator. |
+-------------+---------------------------------------------------------------+
|import |Usage: import class file |
| |The file must define the same properties as the class |
| |(including having |
-| |a "header" line with those property names.) The new nodes are |
+| |a "header" line with those property names.) The new items are |
| |added to |
| |the existing database - if you want to create a new database |
| |using the |
| |the old data.) |
+-------------+---------------------------------------------------------------+
|initialise |Usage: initialise [template [backend [admin password]]] |
-| |The command will prompt for the instance home directory (if not|
+| |The command will prompt for the tracker home directory (if not |
| |supplied |
| |through INSTANCE HOME or the -i option. The template, backend |
| |and admin |
| |See also initopts help. |
+-------------+---------------------------------------------------------------+
|list |Usage: list classname [property] |
-| |Lists all instances of the given class. If the property is not |
+| |Lists all trackers of the given class. 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]* |
-| |This action indicates that a particular node is not to be |
+| |This action indicates that a particular item is not to be |
| |retrieved by |
| |the list or find commands, and its key value may be re-used. |
+-------------+---------------------------------------------------------------+
| |This lists the properties for a given class. |
+-------------+---------------------------------------------------------------+
|table |Usage: table classname [property[,property]*] |
-| |Lists all instances of the given class. If the properties are |
+| |Lists all trackers of the given class. If the properties are |
| |not |
| |specified, all properties are displayed. By default, the column|
| |widths |
+-------------+---------------------------------------------------------------+
-All commands (except help) require an instance specifier. This is just the path to
-the roundup instance you're working with. A roundup instance is where roundup
+All commands (except help) require a tracker specifier. This is just the path to
+the roundup tracker you're working with. A roundup tracker is where roundup
keeps the database and configuration file that defines an issue tracker. It may be
thought of as the issue tracker's "home directory". It may be specified in the
-environment variable ``ROUNDUP_INSTANCE`` or on the command line as "``-i instance``".
+environment variable ``ROUNDUP_INSTANCE`` or on the command line as "``-i
+tracker``".
-A designator is a classname and a nodeid concatenated, eg. bug1, user10, ...
+A designator is a classname and an itemid concatenated, eg. bug1, user10, ...
Property values are represented as strings in command arguments and in the printed
results:
"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. 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
+- Link values are printed as item designators. When given as an argument,
+ item designators and key strings are both accepted.
+- 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 roundup get or roundup set commands, the
-specified properties are retrieved or set on all the listed nodes. When multiple
+When multiple items are specified to the roundup get or roundup set commands, the
+specified properties are retrieved or set on all the listed items. When multiple
results are returned by the roundup get or roundup find commands, they are printed
one per line (default) or joined by commas (with the "``-c``" option).