code-b3b483e0fd5e/doc/FAQ.stx0000644000000000000000000000763707437047562013761 0ustar 00000000000000Roundup FAQ =========== '$Date: 2002-02-21 06:22:00 $' 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:: to::
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:: by:: 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.:: () to see:: (issue by ) Installation ------------ Living without a mailserver. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Remove the nosy reactor, means delete the file 'INSTANCE/detectors/nosyreactor.py'. Rights issues (MISSING) ~~~~~~~~~~~~~~~~~~~~~~~ Different jobs run under different users. * Standalone roundup-server is started by whome ? * Running cgi under apache. * roundup-mailgw called via .forward from MTA, or running a cron job fetching via pop. see Troubleshooting. Troubleshooting --------------- AttributeError: ''_roundup_instance_1'' module has no attribute 'open' ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sorry: in html it is not formatted correct. 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. code-b3b483e0fd5e/doc/FAQ.txt0000644000000000000000000000712007437047562013745 0ustar 00000000000000Roundup FAQ '$Date: 2002-02-14 11:11:36 $' 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:: to::
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:: by:: 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.:: () to see:: (issue by ) Installation Living without a mailserver. Remove the nosy reactor, means delete the file 'INSTANCE/detectors/nosyreactor.py'. Rights issues (MISSING) Different jobs run under different users. * Standalone roundup-server is started by whome ? * Running cgi under apache. * roundup-mailgw called via .forward from MTA, or running a cron job fetching via pop. see Troubleshooting. Troubleshooting AttributeError: '_roundup_instance_1' module has no attribute 'open' Sorry: in html it is not formatted correct. 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. code-b3b483e0fd5e/doc/acknoledgements.stx0000644000000000000000000000020607437047562016476 0ustar 00000000000000Acknowledgements ================ Go Ping, you rock! Also, go Bizar Software for letting me implement this system on their time. code-b3b483e0fd5e/doc/announcement.txt0000644000000000000000000000343607437047562016036 0ustar 00000000000000 Roundup 0.4.0 - an issue tracking system If you are upgrading please read MIGRATION.txt. Roundup requires python 2.1.1 for correct operation. Support for dumbdbm requires python 2.1.2 or 2.2. Big stuff in this release: - Use of transactions to prevent partial data commits - Zope Product front-end - Nicer, more consistent change message generation - Several bug fixes and more unit tests - Much, much more: see the CHANGES file for details. Source and documentation is available at the website: http://roundup.sourceforge.net/ Release Info (via download page): http://sourceforge.net/projects/roundup Mailing lists - the place to ask questions: http://sourceforge.net/mail/?group_id=31577 About Roundup ============= Roundup is a simple-to-use and -install issue-tracking system with command-line, web and e-mail interfaces. It is based on the winning design from Ka-Ping Yee in the Software Carpentry "Track" design competition. Note: Ping is not responsible for this project. The contact for this project is richard@users.sourceforge.net. Roundup manages a number of issues (with flexible properties such as "description", "priority", and so on) and provides the ability to (a) submit new issues, (b) find and edit existing issues, and (c) discuss issues with other participants. The system will facilitate communication among the participants by managing discussions and notifying interested parties when issues are edited. One of the major design goals for Roundup that it be simple to get going. Roundup is therefore usable "out of the box" with any python 2.0+ installation. It doesn't even need to be "installed" to be operational, though a disutils-based install script is provided. It comes with two issue tracker templates and three database back-ends. code-b3b483e0fd5e/doc/customizing.stx0000644000000000000000000005712507437047562015722 0ustar 00000000000000Customising Roundup =================== Instances have the following structure: +-------------------+--------------------------------------------------------+ |instance_config.py |Holds the basic instance_configuration | +-------------------+--------------------------------------------------------+ |dbinit.py |Holds the instance_schema | +-------------------+--------------------------------------------------------+ |interfaces.py |Defines the Web and E-Mail interfaces for the instance | +-------------------+--------------------------------------------------------+ |select_db.py |Selects the database back-end for the instance | +-------------------+--------------------------------------------------------+ |db/ |Holds the instance's database | +-------------------+--------------------------------------------------------+ |db/files/ |Holds the instance's upload files and messages | +-------------------+--------------------------------------------------------+ |detectors/ |Auditors and reactors for this instance | +-------------------+--------------------------------------------------------+ |html/ |Web interface templates, images and style sheets | +-------------------+--------------------------------------------------------+ Instance Configuration ---------------------- The instance_config.py located in your instance home contains the basic configuration for the web and e-mail components of roundup's interfaces. This file is a Python module. The default instance_config.py is given below - as you can see, the MAIL_DOMAIN must be edited before any interaction with the instance is attempted.:: MAIL_DOMAIN=MAILHOST=HTTP_HOST=None HTTP_PORT=0 # roundup home is this package's directory INSTANCE_HOME=os.path.split(__file__)[0] # The SMTP mail host that roundup will use to send mail if not MAILHOST: MAILHOST = 'localhost' # The domain name used for email addresses. if not MAIL_DOMAIN: MAIL_DOMAIN = 'fill.me.in.' # the next two are only used for the standalone HTTP server. if not HTTP_HOST: HTTP_HOST = '' if not HTTP_PORT: HTTP_PORT = 9080 # This is the directory that the database is going to be stored in DATABASE = os.path.join(INSTANCE_HOME, 'db') # This is the directory that the HTML templates reside in TEMPLATES = os.path.join(INSTANCE_HOME, 'html') # 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 ISSUE_TRACKER_WEB = 'http://some.useful.url/' # The email address that roundup will complain to if it runs into trouble ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN # 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' # Deny or allow anonymous users to register through the web interface ANONYMOUS_REGISTER = 'deny' # Send nosy messages to the author of the message MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no' Instance Schema --------------- Note: if you modify the schema, you'll most likely need to web_interface_to reflect_your_changes. An instance schema defines what data is stored in the instance's database. The two schemas shipped with Roundup turn it into a typical software bug tracker (the extended schema allowing for support issues as well as bugs). Schemas are defined using Python code. The "classic" schema looks like this:: pri = Class(db, "priority", name=String(), order=String()) pri.setkey("name") pri.create(name="critical", order="1") pri.create(name="urgent", order="2") pri.create(name="bug", order="3") pri.create(name="feature", order="4") pri.create(name="wish", order="5") stat = Class(db, "status", name=String(), order=String()) stat.setkey("name") stat.create(name="unread", order="1") stat.create(name="deferred", order="2") stat.create(name="chatting", order="3") stat.create(name="need-eg", order="4") stat.create(name="in-progress", order="5") stat.create(name="testing", order="6") stat.create(name="done-cbb", order="7") stat.create(name="resolved", order="8") keyword = Class(db, "keyword", name=String()) keyword.setkey("name") user = Class(db, "user", username=String(), password=String(), address=String(), realname=String(), phone=String(), organisation=String()) user.setkey("username") user.create(username="admin", password=adminpw, address=instance_config.ADMIN_EMAIL) msg = FileClass(db, "msg", author=Link("user"), recipients=Multilink ("user"), date=Date(), summary=String(), files=Multilink("file")) file = FileClass(db, "file", name=String(), type=String()) issue = IssueClass(db, "issue", assignedto=Link("user"), topic=Multilink("keyword"), priority=Link("priority"), status=Link ("status")) issue.setkey('title') Classes and Properties - creating a new information store ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In the instance above, we've defined 7 classes of information: priority Defines the possible levels of urgency for issues. status Defines the possible states of processing the issue may be in. keyword Initially empty, will hold keywords useful for searching issues. user Initially holding the "admin" user, will eventually have an entry for all users using roundup. msg Initially empty, will all e-mail messages sent to or generated by roundup. file Initially empty, will all files attached to issues. issue Initially emtyp, this is where the issue information is stored. We define the "priority" and "status" classes to allow two things: reduction in the amount of information stored on the issue and more powerful, accurate searching of issues by priority and status. By only requiring a link on the issue (which is stored as a single number) we reduce the chance that someone mis-types a priority or status - or simply makes a new one up. Class and Nodes ::::::::::::::: 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. 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. Properties :::::::::: A Class is comprised of one or more properties of the following types: * String properties are for storing arbitrary-length strings. * Password properties are for storing encoded arbitrary-length strings. The default encoding is defined on the roundup.password.Password class. * Date properties store date-and-time stamps. Their values are Timestamp objects. * A Link property refers to a single other node 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. The value is a list of integers. FileClass ::::::::: FileClasses save their "content" attribute off in a separate file from the rest of the database. This reduces the number of large entries in the database, which generally makes databases more efficient, and also allows us to use command-line tools to operate on the files. They are stored in the files sub- directory of the db directory in your instance. IssueClass :::::::::: IssueClasses automatically include the "messages", "files", "nosy", and "superseder" properties. The messages and files properties list the links to the messages and files related to the issue. The nosy property is a list of links to users who wish to be informed of changes to the issue - they get "CC'ed" e-mails when messages are sent to or generated by the issue. The nosy reactor (in the detectors directory) handles this action. The superceder link indicates an issue which has superceded this one. They also have the dynamically generated "creation", "activity" and "creator" properties. The value of the "creation" property is the date when a node was created, and the value of the "activity" property is the date when any property on the node 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 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 of the key property. That is, we can refer to users by their username, e.g. let's say that there's an issue in roundup, issue 23. There's also a user, richard who happens to be user 2. To assign an issue to him, we could do either of:: roundup-admin set issue assignedto=2 or:: roundup-admin set issue assignedto=richard Note, the same thing can be done in the web and e-mail interfaces. create(information) ::::::::::::::::::: Create a node in the database. This is generally used to create nodes in the "definitional" classes like "priority" and "status". Web Interface ------------- 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 (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 the access through its main() method. This means that you can do pretty much anything you want as a web interface to your instance. Most customisation of the web view can be done by modifying the templates in the instance html directory. These are divided into index, item and newitem views. The newitem view is optional - the item view will be used if the newitem view doesn't exist. Repurcussions of changing the instance schema ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you choose to change_the_instance_schema you will need to ensure the web interface knows about it: 1. Index, item and filter pages for the relevant classes may need to have properties added or removed, 2. The default page header relies on the existence of, and some values of the priority, status, assignedto and activity classes. If you change any of these (specifically if you remove any of the classes or their default values) you will need to implement your own pagehead() method in your instance's interfaces.py module. Displaying Properties ~~~~~~~~~~~~~~~~~~~~~ Properties appear in the user interface in three contexts: in indices, in editors, and as filters. For each type of property, there are several display possibilities. For example, in an index view, a string property may just be printed as a plain string, but in an editor view, that property should be displayed in an editable field. The display of a property is handled by functions in the htmltemplate module. Displayer functions are triggered by tags in templates. The call attribute of the tag provides a Python expression for calling the displayer function. The three standard arguments are inserted in front of the arguments given. For example, the occurrence of:: in a template triggers a call the "plain" function. The displayer functions can accept extra arguments to further specify details about the widgets that should be generated. By defining new displayer functions, the user interface can be highly customized. +-----------------------------------------------------------------------------+ |The displayer functions are | +---------+-------------------------------------------------------------------+ |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 ids if the linked class has no key property). | | |Options: | | |escape (boolean) - HTML-escape the resulting text. | +---------+-------------------------------------------------------------------+ |field |Display a property like the plain displayer above, but in a form | | |field to be edited. Strings, Dates and Intervals use TEXT fields, | | |Links use SELECT fields and Multilinks use SELECT MULTIPLE fields. | | |Options: | | |size (number) - width of TEXT fields. | | |height (number) - number of nows in SELECT MULTIPLE tags. | | |showid (boolean) - true includes the id of linked nodes in the | | |SELECT MULTIPLE fields. | +---------+-------------------------------------------------------------------+ |menu |For a Links and Multilinks, display the same field as would be | | |generated using field. | +---------+-------------------------------------------------------------------+ |link |For a Link or Multilink property, display the names of the linked | | |nodes, hyperlinked to the item views on those nodes. | | |For other properties, link to this node with the property as the | | |text. | | |Options: | | |property (property name) - the property to use in the second case. | +---------+-------------------------------------------------------------------+ |count |For a Multilink property, display a count of the number of links in| | |the list. | | |Arguments: | | |property (property name) - the property to use. | +---------+-------------------------------------------------------------------+ |reldate |Display a Date property in terms of an interval relative to the | | |current date (e.g. "+ 3w", "- 2d"). | | |Arguments: | | |property (property name) - the property to use. | | |Options: | | |pretty (boolean) - display the relative date in an English form. | +---------+-------------------------------------------------------------------+ |download |For a Link or Multilink property, display the names of the linked | | |nodes, hyperlinked to the item views on those nodes. | | |For other properties, link to this node with the property as the | | |text. | | |In all cases, append the name (key property) of the item to the | | |path so it is the name of the file being downloaded. | | |Arguments: | | |property (property name) - the property to use. | +---------+-------------------------------------------------------------------+ |checklist|For a Link or Multilink property, display checkboxes for the | | |available choices to permit filtering. | | |Arguments: | | |property (property name) - the property to use. | +---------+-------------------------------------------------------------------+ |note |Display the special notes field, which is a text area for entering | | |a note to go along with a change. | +---------+-------------------------------------------------------------------+ |list |List the nodes specified by property using the standard index for | | |the class. | | |Arguments: | | |property (property name) - the property to use. | +---------+-------------------------------------------------------------------+ |history |List the history of the item. | +---------+-------------------------------------------------------------------+ |submit |Add a submit button for the item. | +---------+-------------------------------------------------------------------+ Index Views ~~~~~~~~~~~ An index view contains two sections: a filter section and an index section. The filter section provides some widgets for selecting which items appear in the index. The index section is a table of items. Index View Specifiers ::::::::::::::::::::: An index view specifier (URL fragment) looks like this (whitespace has been added for clarity):: /issue?status=unread,in-progress,resolved& topic=security,ui& :group=+priority& :sort=-activity& :filters=status,topic& :columns=title,status,fixer 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 are displayed. The filter part consists of all the other query parameters, and it determines the criteria by which nodes 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. The filter part selects the union of the sets of items with values matching any 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 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 by activity, arranged in descending order. The filter section shows filters for the "status" and "topic" properties, and the table includes columns for the "title", "status", and "fixer" properties. Associated with each item class is a default layout specifier. The layout specifier in the above example is the default layout to be provided with the default bug-tracker schema described above in section 4.4. Filter Section :::::::::::::: The template for a filter section provides the filtering widgets at the top of the index view. Fragments enclosed in ... tags are included or omitted depending on whether the view specifier requests a filter for a particular property. A property must appear in the filter template for it to be available as a filter. Here's a simple example of a filter template.::

The standard index generation code appends a section to the index pages which allows selection of the filters - from those which are defined in the filter template. Index Section ::::::::::::: The template for an index section describes one row of the index table. Fragments enclosed in ... tags are included or omitted depending on whether the view specifier requests a column for a particular property. The table cells should contain tags to display the values of the item's properties. Here's a simple example of an index template.:: Sorting ::::::: 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 sorted according to how many links are present. Item Views ~~~~~~~~~~ An item view contains an editor section and a spool section. At the top of an item view, links to superseding and superseded items are always displayed. Editor Section :::::::::::::: The editor section is generated from a template containing tags to insert the appropriate widgets for editing properties. Here's an example of a basic editor template.::
As shown in the example, the editor template can also request the display of a "note" field, which is a text area for entering a note to go along with a change. When a change is submitted, the system automatically generates a message describing the changed properties. If a note is given in the "note" field, the note is appended to the description. The message is then added to the item's message spool (thus triggering the standard detector to react by sending out this message to the nosy list). The message also displays all of the property values on the item and indicates which ones have changed. An example of such a message might be this:: Polly's taken a turn for the worse - this is now really important! ----- title: Polly Parrot is dead priority: critical status: unread -> in-progress fixer: terry keywords: parrot,plumage,perch,nailed,dead Spool Section ::::::::::::: 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 message takes you to its content. The tag used in the index may also be used here - it checks to see if the nominated Multilink property has any entries. This can be used to eliminate sections of the spool section if the property has no entries.:: Files code-b3b483e0fd5e/doc/getting_started.stx0000644000000000000000000002166007437047562016531 0ustar 00000000000000Getting Started =============== The following instructions assume that you have installed roundup. If you haven't, you may still proceed - just run the commands as "``PYTHONPATH=. python roundup/scripts/roundup_admin.py``" for ``roundup-admin`` and "``PYTHONPATH=. python roundup/scripts/roundup_server.py``" for ``roundup-server``. The Instance ------------ We'll be referring to the term instance a lot from now on. An instance is a directory in your filesystem that is where all the information about a live issue tracker database is stored. The data that is entered as issues, the users who access the database and the definition of the database itself all reside there: Hyperdatabase This is the lowest component of Roundup and is where all the issues, users, file attachments and messages are stored. Database schema This describes the content of the hyperdatabase - what fields are stored for issues, what user information, etc. Being stored in the instance, 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. Web Interface The web interface templates are defined in the instance 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. Instances are created using the ``roundup-admin`` tool. Command Line Tool ----------------- To initiliase a new instance, run "``roundup-admin init``". You will be asked a series of questions: 1. Instance home directory 2. Schema to use 3. Database back-end to use 4. Administration user "admin" password. 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 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 start. Roundup is configurable using an ``instance_config.py`` file in the instance home. It should be edited before roundup is used, and may have the following variable declarations: MAILHOST The SMTP mail host that roundup will use to send mail MAIL_DOMAIN The domain name used for email addresses ISSUE_TRACKER_WEB The web address of the issue tracker's web interface The email addresses used by the system by default are: ISSUE_TRACKER_EMAIL: ``issue_tracker@MAIL_DOMAIN`` submissions of issues ADMIN_EMAIL: ``roundup-admin@MAIL_DOMAIN`` roundup's internal use (problems, etc) E-Mail Interface ---------------- Setup 1: As a mail alias pipe process ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Set up a mail alias called "issue_tracker" as (include the quote marks): "``|/usr/bin/python /usr/local/bin/roundup-mailgw ``" 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 To test the mail gateway on unix systems, try:: echo test |mail -s '[issue] test' issue_tracker@your.domain Setup 2: As a regular cron job using a mailbox source ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Set ``roundup-mailgw`` up to run every 10 minutes or so. For example:: 10 * * * * /usr/local/bin/roundup-mailgw mailbox 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" will be "``/var/mail/issue_tracker``". Setup 3: As a regular cron job using a POP source ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To retrieve from a POP mailbox, use a similar cron entry to the mailbox one:: 10 * * * * /usr/local/bin/roundup-mailgw pop where pop_spec is "``username:password@server``" that specifies the roundup submission user's POP account name, password and server. Web Interface ------------- This software will work through apache or stand-alone. 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 ``ROUNDUP_INSTANCE_HOMES`` on the command-line using "name=home" pairs. 2. "``roundup-server [-p port] (name=instance_home)*``" (hostname may be "") 3. Load up the page "``//index``" where instance name is the name you nominated in ``ROUNDUP_INSTANCE_HOMES``. Apache: 1. The CGI script is found in the cgi-bin directory of the roundup distribution. 2. Make sure roundup.cgi is executable. Edit it at the top - ``ROUNDUP_INSTANCE_HOMES`` needs to know about your instance. 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 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_DEBUG "0" 7. On Windows, write a batch file "roundup.bat" similar to the one below and place it into your cgi-bin directory:: @echo off set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default; set ROUNDUP_DEBUG=0 c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi Users ----- Users and permissions ~~~~~~~~~~~~~~~~~~~~~ By default, roundup automatically creates one user when the instance database is initialised (using roundup-admin init). The user is "admin" and the password is the one you supply at that time. If users attempt to use roundup in any manner and are not identified to roundup, they will be using the database in a read-only mode. That is, if roundup doesn't know who they are, they can't change anything. This has the following repurcussions: Command-line interface The data modification commands (create, init, retire, set) are performed as the "admin" user. It is therefore important that the database be protected by the filesystem if protection is required. On a Unix system, the easiest and most flexible method of doing so is: 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):: mkdir instance_home chown issue_tracker:issue_tracker instance_home chmod g+rwxs instance_home roundup-admin -i instance_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 gateways, then be sure to include those users in the group too (on some Linux systems, these users are "www" or "apache" and "mail".) E-Mail interface Users are identified by e-mail address - a new user entry will be created for any e-mail address that is not recognised, so users are always identified by roundup. Web interface Unidentified users have read-only access. If the users database has an entry with the username "anonymous", then unidentified users are automatically logged in as that user. This gives them write access. **anonymous access and the ANONYMOUS_* configurations.** Adding users ~~~~~~~~~~~~ To add users, use one of the following interfaces: 1. On the web, access the URL ...//newuser to bring up a form which may be used to add a new user. 2. On the command-line, use:: roundup-admin -i create user username=bozo password=bozo address=richard@clown.org Supply the admin username and password. roundup-admin will print the id of the new user. 3. Any e-mail sent to roundup from an address that doesn't match an existing user in the database will result in a new user entry being created for that user. Issues ------ To add issues, use one of the following interfaces: 1. On the web, access the URL ...//newissue to bring up a form which may be used to add a new issue. 2. On the command-line, use:: roundup-admin -i create issue title="test issue" Supply the admin username and password. roundup-admin will print the id of the new issue. 3. Any e-mail sent to roundup with the subject line containing [issue] will automatically created a new issue in the database using the contents of the e-mail. code-b3b483e0fd5e/doc/images/edit.png0000644000000000000000000002335007437047562015500 0ustar 00000000000000PNG  IHDRZ%UPLTEJBBcƵ޽޵ƽ{kΌ֔cƄskZ{{{{RssssZJJB99{{ֽkkkRBBss޵εcccޭƭ{֔{ΔsΌk΄999Zs111J99{{)))޽ֽss!!!ތֵkccΌޭkkքޥέƥBk1Zc911!JΔ{kkcZZscc諒քRsJkνBcZ9Zk9ZkZZZRRRkZZƵJJJ{cccRRƽBBBﭽ祌9cƵRks֜s{sZRRRJJ絵c{>- IDATx}u%-MԞ[C\rҊu4fZ6-2$\96KδrAWɈƑtBZH˜$W)$u{s{'˛-Û¬ L9~qA@+#w\k?ss`εL+7oܹsqWp 2k\W]'~_[Yyʹsfbl>k>~>Ǟ19{_y9?ZvܮН/]昹g'o.ܒyC&q]Y\av۟V{#ܱcЮud/s&40p]\zbs'/ݺ'o=qne'o]3O>uog=uk7Y+7/'Z0o>/̙g>ywZǖ-^u/> W~ڱ_5X^מ+[WJ/]6\4]uSO:뗗vo[ډsKκr[/>"*/Υcnҙ'./^>sno~ܙ']|v39qĵ[+JSאa Ɛ7v_[5..};-o9c<;̵K]ڙ'6 &<}=\k?8\U2hsOt\GBϱ{:z^*e< mU3A-cp"ѱ yp-`VY=T])x˞p-ފf9N ij|AWo Y [O|B/ob714zoʷYPrQ Lfi 6oK?͂0oL /4[҅ bJlƎkie"? j:X͆ V e6 \&S z#o> mp2nJ9g7㺵,pi1۶0h,|T`C@OMAcp9~0\k?ן}mp_G 珜X{^>||$;j>!njmCjzA oj߹ a}-(& d̵-3*>ό%\wmp=z|_[['xٯs`ε̹p~r̊'Jo䏭ĜNӭnE[<=k&x2X3~qyeqSv32?<8ѡQq%WuA [ÕJ/h*ۦ,JIƕMи]^s)+H\AZI+ VF4h\PEk\Un WPJ-+K_3ƼT %Wި@ךhgבq(\^Fx>eQ#@/iZmsN.WGŤ:q~4m~k?ss *Ջ@r_.d݀ѽ A"Wrd؉\dY`hP¸;WU"u (7Tl i`&71YWY=j|c-]vJfq@) x)2={6pɜ^i$'YwO!W ~>%Mk SF~:^qcM\jCesCو{+p??ܝhl^0Ҙ8z \:z酿qG/]zۇWW}ҫ/?/'^r=/7DS\B2zĉ\_tٗ>ǎgrҿ}Ç/=z}_^:`jc\[%G Gz W>~o+gO_9zի.^x#^8 o?78{= H呴ug\8[=z=˻~k+\ݴk?ss@rjc5F{H8ss]{`\?ixϚs\k?ss`ε̹9~06pq5us c*2M}X.2We 9]mK ZZUq?+X gk[auss`ε̹9~ =O_#ۉ|c+5kzs~|mӮ/~Ҙ6WC}G_3?~߹&c3ơC7~ϴXз~>?|o|ſoΚzu߾q77W_?N\oan_pp߬]);Ĝk?:N"C"vS ER$,,vǵκ6`+|F9VAuF ɤ>W]M??1),vŵ2#IUigD [9kU0E>YfH 8c$7ڤ"fL~Q28 !sʨ\LKK52p)eTL#׌)Z,4բNLJL$VnF\ $JQVVc,&꙳py`q\䪈L,*d&*jc*x H9FBKflĕK("˺~_,؝ c@@Bb$$l֢Y-c8ȣ}+v <#NUUkEz,\qx=0ƪo[ņ#Dҋp8l656$Id׺ؠc.#Wx˵:[ȼ5nBLTe_ҩ22YREA1Z('\TEeh_2㽎;E)\AC ܲ('PTUZzJTCkEBTdRIVӠ?7J5lz[;;K͛nl,[`xiH5n x\'qAѡ-u$t5++KKґ z*UڤJ}R=`I*KK˺n$ig{>s=e16}:fڗ y̮VW;kBy}R_.1אmm)>\V[Ѳon~ᄭlLY$(k$Rt\Di;t=/OއL2&%K+r I4$1B)n<#:Q#צ̌Y1HLdYUa$@3PP)& UV 'X>;k%uyAȃ2瓖ƞ+p kd>m* ڂU:kPW?avTWtV3Lծs`ε. [,-.Tobw^V2SgVKW-KIL].ʂN$.wvPjwt=$уDy`dŲg~Hպ|lL0.]pu}//]"kہ_3^uTkԔ4\`W\;˨*FV_P: b:֩dyW{0ԬkE=̪>a-*M($cQm/ɓx}e@+0UA<:SZ&p:+8r,C9\`H _8"9q&:\iL onȑ+bDhR.~Em ݽ CPUr:\&K TÍ,T Z+L[BM 0J:THW[. A}vtB{2 JC}&*=-v˺Tm|[uQ[UһSh<LI^ݼNˈ5n[7yosErRA5^]Ӻι X1Y+Ы;XdHo*80Y,YAts mQD2Э4.tYBot p,k݄d n4>CDƭRXw4^>Fy|Zh,içDP#зƌ̻Cmp5<SڀD}u˵lF$P\ 2#Q!Kue:ճZ4aĤb,0SDM\,uWO&@3͠ 0aZǜ:2+Z 1Wg$0|ƹǘss`ε̹w#/5#<gfLL0h49~0Zy@_zs`εDmc?^_E5ӏ`_hN#}?OS#/~wOp|Swz>#}?N}fk+ߗYi Yc\3̹9~0\ZԮ`3|18Q7|D`xL+&øRSqUfƛPT9$(Bk@Dĉgcpr)ː,# 3]N2tH1eUT. |xg섫AXd$#:*Y8 1\hMqfP& %w%)&2GyLD^u&FSE9rUT+D*$Āʋ vA1$:)=EW} c1C(xL\3j{EJ cCG)0-"7ΐ jFۗMPWdFϼeIpWW!ÕqMA)`; OI9-Ixq&(KYFuӊvwnp]Q =rV`RQnjsrz*4 aP $Vs!THF3窹a9"d{*@f4T\gɸZf>V:ՃwRJkk)*![NW6r)8ZC'Xe̫d҅5cn}\AM : s4V+RrI[FhZ)pE J؁Eݐn-*L"WTXIDƟ Q/cVQ;*`H" xAȴ`:H9I\z3 :gntwg3W.5d`eJuƆ"˶bHx^BR" eڢ6Q씫9:Y`=$VaWhM=܀$ m^F Ӱەa"N?ԎQuT%H~ZxM( "M*K :uQSrE$P\6#wnN}bZ9(Oo)BE%1M4i1*qzI\a9ͤ`"4AwHR"M!4C`yZw\1-dTH 65 o)0 4$U;_X5mѾѧm2'WŵiTNĤb^AJժh  "fK ;|kQl||6ULu{aε̹iru3[UcvUk |eXSP!9 @E-ΦsYV򔅊b"Dc`xIS: LR $FS$$Qz8ɔգ;0RNb*iiZF΀aF#y;4hJL.IhBe%,\f2&E,5ء)&Ҕ`n-lH 9B1ykL! vьkZUF+vMY!eDvRB)f 6ÄTL5p(5|Ld>I@/VӸI ?}Aߘs?5\9zYLƿ cٖW9-'iGD~M07vlΰJ:Ltwɋ:% : 0äu>8J"Q34ajJܝ=`O8e|T<- \Eˠ]@zȵ{0SB Ơ3ڪaTq2(>l;pW\u bȭa#u˵.( m)E+$" oifLQERN^jm}Jj9Tȵb(-kylF0O|[ '%%aY,<^n2=kT0s V3hQD~+fܔ1 nSvM7U*!᝭m)#]Nw>Uœ1jۼfvMŔ7*%f]=iYQ8k*a@v+kB('CukhK9=h}f%ѩP]?ή鱼 &jn0BZ.%BcrMٍqgVXA65ke8JUmO(DʶKfYlȸ& ]*Xו,qj.W/qi3#ZjF2:7Q6>xj\~f0[ &~G0-tvs' A/ Z+V]M. )tHxS+<6 L #3 9GO+ 7qvV.XQ~kSig4::bqͲbNBzd$NYlbTEcR54 9)ft#mJH2h!”~$V%Xdë̝IA1mM zjr 4?k3h2=YeA)FrMV$քvIO6Ȯ``[z]0%x(>X$EHxIa\@m'3P짊lֺ̟r]o$7lQupБ-Tػ F%J5,!BIDATh08㄀ C5f/ r=VjEN\I֦^l*ӆbEble۪lخ 8$]S4)mo8U&HjLv u n+ F˪ Rk$ gX6\k?sW 'ǟbWgص#]q o4VtiLRmf0"z޵6[#̦&sn2hҨsS;68X*Vz̥h'Bs,#  j5:"=&!ѠZ,A?`ZZ),K2Qguj$C@R5T)jx m:0havjÔZcg0G2ʴt(Je)Ec ܫ'M1wڤ5#\ߨ I.5!ېAFbա&lhuzn!N e WYE@4<&3abyL|<,}y*"!1  U٘M"4ˉNQ,.ʙ7&OILXD  !e$)=F$X$F*Ste]+C5FLd@ P1E#Z>0ENE@ OK&8 u"z7Ŭb[|2NPs\/ȵ .Nv,]:86vƠO5،kl* sSZi6.,t0ⷝ1 %'E2ap%M~,nhK eŔm]U[޴eѷRyUieE![X2YLdm 8;9\~v#Lw2ItEqgQÇ.i\p.svkmN^\j7Wާ,TmuVu!=S36c̹9~0i xTqگ.H7S/IENDB`code-b3b483e0fd5e/doc/images/hyperdb.png0000644000000000000000000002333607437047562016214 0ustar 00000000000000PNG  IHDR`l JPLTEckkcck֥!s{199{{{119)11Zcksss))1֌!))kkk!!)ccc{{999111ޔZcc)))֌!!!΄99BRZZRRZ!!JRR{JJRBJJBBJRZcέZZZRRRks{{JJJcksBBB便ZZcεƵs{{ss{9BBksskksXO IDATx_VO2v(T) e(XLtth,EYrasq}! I IףVy<%tL'5ļ&|b^Әzļ&|b^OkyM>1'5ļ&|b^OkyM>1'5ļ&|b^OkyM>1'5ļ&|b^OkyM>1'5y/(Zעy-Zעy-ZעI!˺vo6~ܐ|bHݑrëÇgcmx}Stwi}z^{z{yo;N6Фl|>]mI7Ct̅5:n0mg}8CQ+mn6~' 4)b7b!UCoS|N/nK<ƛa܅v!::&l@=zGk$]uMp?x~P &:{,Ös bY+Os1܇{SWKG rS—Flq\8i$; vU6dGe/#D!FHMۅaWG,rPq2ƿmB'>$/ϗghl{ %eø{\@/r8ta髟qQJM}iĠ]}Q| Dx@nZ8LJN*ɱJJ[(>u/1b$ܵ "fN"kEn&'f2Okz"ۓ+œ,ybO]=bL2?qb U^k+ ňU/M&0LMk_VsFUf\Zԗ0d΀1|5^Pn7 w}-b<JV%r̥0?^˫Z?(Y4]F%*142:U,9US%I'5N1-gЯb#y?uwaUf+N2˳F䮿>`S&q:e;`L"{E狼J,TtbT[6Ҝd0rBx+!vOL||z\R< ѱlO.Nss#G;ij. >k * xwI;c0r!m'z~kt^&~J>]cu>8pyKD$NDm5ZS]UC]pM's_ Į\pG k88AYFۭ m'JX b h :8b Ûdpz3E/dB\;XWx 8~.keE1m$oX6uLD?0F4|8 taUķo z_( ]W8'Ay4bw`7(]&uEm?U1N,5}GXAgxPWq(\oR_^syd/b߆/SF|ۧ/}OO0 uPѪQ͛]\{}-ٓ#h|qtWJZl-dǑ/p±ooNm>H즋cz`ǗRkIyXv6*@C"*ĉF#FuB5T)5ZhE?ф||c6Ǣ+#&q"IOO#:('Ki&xS@ ĔE_!NU*G}):LBbn&b"3/=q!ɘ:a,$bbpl\|tuX0T S7t<}%:֮P1V)0!'}n%czDW%3$]Jg3W|198.֝J6c[&^VXW+2V{1bHrW-4n$TeZ8QޅXɖ i=LDV̢eJDg'u+G☺MWIۈu,՗e=MDLˈu;Qfe$NT7"f/0lj`ELOKfUĸ^! a$NToDڜDhKGa* UItHXRN{DTk TDI'gI4Q&hT8L3 B!N$/lɊN)4$ݢc!($s+I4" ItOt%2$Ve3lyIw^1\l81+:$6Ef>LXD(>8+P= C #DF)^3Va"a:[Ңc!5Y>TJ͆d乆 h*"ZĨjZWZ^EuH+(7ͤ)\V7lqQUm$2bVX iac$X4+VE+!-ZRa$}]1a)$EM)yi1]I1Fki8P+fDK)>dc%kbtEL1'Sgtkm$ibu8BL{1!ّI#E=Z1E=x0УU8ӚsUL4&%6b9׉ItYtgW8HLcĴZuOHH*9өOČg 8;KFpxn0~bB3eSli;1 DQ)>@2 *1ʐL)3fn-I`{yOMl !A|4"U*sT1#g(C> )j|FR&T.\3^oUUIٞTak>fS&_`?Q$ sJJ81d"*k( ȣ K6]a9K`ѓ / \-2!.K%Lc ~$6U%dm OZs^OB"Mtݿ0D#R^$;ROxDT:U;:U=Y ؠ^gȤ`FXOYNH0\+|fG6 */dO&0"}bmHJJo%$&x sѕsOHE`-By*ʈ'$"2:!7:Z{9C%B tHEdk!cPDxmҴ筞""DM׆PD~BX|bFӗOLW>1'+ӕÒVE_E#23l I-h#f&ve"5ӁL pl4[%f%^5йf{.Ȱ.r6Ys[,g-4X$f):{WL5Uf5!+ZIYm-Dڸ”c+bB9`mqh6jogU>k,Dg^U̳,fö,ӄ`Y>^DnlU/}V:"uk!v 2B:[*Ԭ u6%jn*1!T*Eb ?xL,ʏj{]j㪳cycW0z9N!KS6Iw9:LpXgWM,7 bJ2@M>5 Lg֜2_K]W/Jͺ5!6>cugiEعG2^z#Z1ʷدa*W}t`R"21?^z#Z1*QY}_:brs˪hĠpT+`G e\?U.rF'Z%1wUp⓱OZb{}|'Z11W=mzNjvVMUcrbd][GfoAO'FNJ4Z0\1%mu9A ܇/]|lWr6 pb},oM 1e mw9D=c9K>8]DN\>_)b}dVo2_fkA#/CKr>F'r[qwͶIbnq'rY ѳmM\&Q9J5CD\ohL ;OL=TSԓ6\&0˻wKV+a3_0KwãW_%s`r,V\B o2L׹\X@ECn!}t0 3r~09Qk}||gQyrb>vw#+UUgꖪ>.]S7'r1 ##z~"7sS{mɮ~"WsHiɿ'r -t!e3/w#10Og?\J,r1Wh[K fNn#FQ:åaؽ\Gݾ WV_Wi8>"+smxhI57Nre~"7satup#:W?+ASビmsIy:W?;~b HB@ZȝĈ`VC<詜@j]D.%ɰSCAtu@P޽RW?;}`e드bU޽r'#+<ҟ$KqrѺ<H=RrD}OGҤ"?(KU:e]K r`EᵔcqKvN&ãK{rZ^7WP,~iW!wg;vab_6#!+FK>1{e_h'f-}Y%/k~ba_ߺoK>/H6ֲ%(me-r?14T#vm%f-x3 ѻ)B/6Wst>Dгxk+$ogpgcn5O U!>fh#B0dX{m6JGN] 1:7)>A瑴Q!S6qӵVa#BWq!8*~m1^,R1+qw9\XKIC(YHI>:A;p2ZH*%6[n'$mRoxAHGDbYG]\{$v~$ J'% Nnoo r@C3#}WH޶O!w^#<[/z0Ғ~9p+[( l:{,/$e:RW):/b,n@b!kϮ5:L^Pq\8~IHƭ"G2TN]H!75Dz8bq&q ~2~:zuqM2o({ sC0;kijL,q7~ <+>pdy9(_[qV^oMQV_T~ ϲ1I"[7e}Y%،.oH8xH'Wdz$^Z$FSR#1*/kWe&˴|b^OkyM>1'5ļ&|b^OkyM>1'5ļ&|b^rk]׌t+U SkVĂFD~u1~=[[@,ɾ u2!;Vʙ"F,'<6Y&@$Ԕ=pHm-E@lϮʟ$N>[XxkuF[?R#8^#m^**{x1 r ~.o"<>:$.aK2yvxsUmSt|| O ^~SzO龩j?VP/π>+{''NݯF9翆$Pʸj=DbwxTÅ}IKv+ĺ"81rL&1|sݱc7yzf7˯/Yy;W)P!/ ∲ݾ~!-B e1'5ļ|yF>1'5ļ&|b^OkyM>1'5ļ&NYdrKL S ,7& Y&V^>9CԻ XAd LlEXȾUb1ҨzGoz(^|)($ EO]o:*K^ u"@OK@aS4v vey%ùRZ"2҆LJvH{T/%d*qe[pP QmluNm$Ka | 4c %׆å\V.Q\/Q؜}@&Vcԧ f 6$Y VHaٌQ! %"ڡ,Y|3ϳ4C$j4r}אlA81T  In*lGVE9RXIw¥qݩb2 p=@n{6J 妢@_UB6ѐEX&Q XQiBiY16 *b  &˜ $T=y8IHEBБX^SVWT4#d+)/-ugJJ9S`XFɝpl]WjXQmA?!A;Ao5 $D'^*_!rVB!\ޏ Ihu-IT 16P 谢&|J<[OHt 5D'r Ju`K 1l͖R:,6yXJgVΰ|b X"60"0`(QHnې tipU=1^AZgUH$(PKEBǻI*л |\+&v^mF"g zte&_&B=M!)-X*(섶QF+ƅd``1886:PحthZIpvn n+ >N<4XG'YҎt;! LvRRls!huhӐhY7Hy1 "vB4&j*(1 p'0xނz#ɧfd+Ɯ/ qΙHZ=k؋9P77${@uQSD6!=\7am:]ńJBu͋D5?bDJ2laJ)rfg"wx~@l7^AdM׼|b^OkyM>1'5ļeZ˰]qIENDB`code-b3b483e0fd5e/doc/images/logo-acl-medium.png0000644000000000000000000001176507437047562017535 0ustar 00000000000000PNG  IHDRJ6\ΝPLTE19B9ZB祌JJRkc{c!ZsRޔJ99BsZ1){{Rc99BcckB!{﵄ޜ!J)R99c)Z{c9)k{)!ZJ1kc{!ZJJ1k!Rs)B{kZ){J)Bs!Jk{ZJZ)1{scsk))ֵk!ZJZs{{11BZRRRZk!ֵ)!)1)k{J)R9ZZZBJ1ZZJ{BR!ZRcJZZZZsc1ZZJZZs֔1cB)Z!R!1sks1RJcRk!֔έ!{skcB{{Rs{ks11B1R)9JcR!!9Z!cRs))!)JBZs!RR9{B)J!)kcs9ƽBcZs1!B!kck֭Z!J!cRBB11)c{)199֭R)11Rs9k{s!{s99k1Z)s9J)c{sZ9{Jkcc)kcRsޔ֌z5tIDATx[T׵.ڐ8¥ RD$XH#hXSĔ)0ī6R|T QUx)kO~e̙}ޟ}HAS?r:N1j:'qܵ㜆S';Dn#:EfWŧ8Wקd /i9g?|51 :"(/$I {0)hL ؍KmXiΤ}}BX4MSIÜZ#"Zzͫ&<=ϙsᄄn7Fv, 0s:!tuz)<)O`bASHn y|>ʪcΈuxqB>~E)3!3uz“l%8r,Q𣌑4б/\zG ` %ǎ8iiAZWFÇ粪Z4J0! -3Goq{ *?D3Yo5' ]4Oh_L`;0f盏yG }P579;x8r0a0̥~_U<}jܫï/_ΰn+{PEA"`_ !x_W^xxIZˊCr aRzs/&LE*/^re!?Z.kW]J)+\[{پ=\lef<8~ժpf[E^F12kktA匸wV>>ߟ*(45*ҳ&+}k!vE7q2Dn==1 ϕ [5xL5}y!l;dn&ǸL9Ύ򹀉fídӯ)HqN8|v&fB(%G/W2M?SXq~l7Ie |_ |j xŽ9~r`׶FvBW;pvwS #JMɖ14E3V* &D^VmP^H^vX)TOEӹGrk/ևvtyF5򀪰5Ck֬Yzhꪪը5xc[23/wՑP!&*f.'*ÂKk&7ɡ_(d#=J5'kn];lv]>\ I]-LQw&) B$ii0Keܕrkݻ[`-kE w= 6lnj\Ӳ whW_=m ;eb0e$aRCL lF˲_ \ \(_3PFY?:Mv'>[-w<#JEu-3#Ž藥s宅 ԙ ?BxKD!ꝎjY=Asً~?Xo^ >_3^ A``QQc6[W)7nNfj:Ob9G;1+Nou _y} WŠַПܩ+V:|2<}r2wj^[O`(@>^_HGw<ղu#eF|F`،醅;x{ـDVFEF#3=zbsp 1j,J*\_r/[4ęn4C[vknKFa-1}2S{L /Iw_ra1 E4E-&I_][58JӷjH6lT\_cs}fR{"/#R߻FnC$D$ I]x>IgTz3}2O6I$1Q]]><_5YFH""BBBҢL^%! *uu}QE{-zԽ\'!/-le {K/[#?Ծ,)2w6z`y$MsAVp[ +Af=#xupѶ0m Y Ɨi[!. OGJkCSim}zwPm),_|YVh 7xQ>$+sFy *SS8=)uυ77 ?>ε<;83rrw|\zS倍7J3DL͌'tv Sp' ;5Ojx*'C zƇ2Nr'N#_>Oz5.d`ξ'UP:P ('`+ΉCxT~s\`>GU؝ȱSfrJ!g+ɓÿH%z]}|oGF}7fA̞޳cX'L4JXxH*7/WvShףB:Qa(L{rU؞lؾ-cUz13vwwW؎j8а6!uIi <͛%}Mk!2irl% =}a:JQ̎C6|H߽pU1|lzssAAED]Fұ1`5cd@=G;+/t:]L-Zi4mutslOO_sc~ӬnK߭3l1'p疣G)бƱ&oR•jL$8e7@))&S+vQMc#=#(U۱B׍=[*(`MJ$njj،|;G5 >) R.n؀#(la` Fc6l麻yx GF.^1zd:s S3mXnzџu"ҏ-ޛ SsMz!t%Gb7@DvaA[V̜93fm) 4=S:1 .&;'"a!s"g&ookkwpπfJc#43F%A%%"I)@tϟ?-UR.8T2yڙ!.J !d.!1HANJ0CG_RR;Ry !< +Xmlbw* "A">X2p;;FR& ;R1kV322CǙa1DR&x9$ʰJbRL_1[gHaÅ( ) gP ?> c2 &-a.äm?&xPS'wG so]NO\"B4Ѵ?kuPM-JIENDB`code-b3b483e0fd5e/doc/images/logo-codesourcery-medium.png0000644000000000000000000000531107437047562021472 0ustar 00000000000000PNG  IHDRJ6\ΝPLTEckk筭便ccZ199{{{119sss))1kkk!!)֭ccc{{999111ޔZccssk)))BJR֌!!!΄RZZ911!!JRRJJRBBJBB9RZcZZZRRRks{!JRJ{JJJ猌BBBZZcZZRs{{)19RRJksskksާmIDATx횏WVJTlb-6چYKkŵ㾙yۘ ovwX`"{]~Wߕw%{]~W __BL{a{17`r!2JCQ,xIpم;?|gvWPCZV( h3}MQ ǿOn` yJw}dm\lp &h"qbW_ilh0q)C7q}&7gO D@yoTN'$>ݸ) n‹و _].ۓ2g%/pc(Kfb1iU]₵[*5n.ɔ<&Z@[#%# ~$ "dgYם)H!xL"> mAuŇT9Ci[U8 <W LˁcBFj_/d(iWr BWaL "a*YvTR\Dݦ p"baxgjY 53 N] /fAJ54}28RV+[#Z_( Fvɳ)x7m6`uO}/#x[ 8Z;/$ ޥ~٧lx,iE[:can.]WDĥ 4O4xw (T͟!ߋǸY煛:f7mpQ|hgxq5x6ތޚ;~ jP4 My1Vm)`^jw Hͳ/a~zS^AMR3+n0ak:|YmS,78jvhM dMAsw!|d`d6xFOըlF?#oBh dx!tF5 fz K;;'ا0MrWѧK2<>cژ9KG$QRR^%X5O UpB"D,HB^+b)®aPJPfCѐ]Ga_1iݲtv7 162ufkM%O{w(O甫=Ȼ-eՕUf|m*]KΥK*˞kY+յZI|y\q7 "aiqyoTf` ߌ'yi?~i&|ggzI΁X̟ ˫f_L&GSK ½6?$~7< ~e[Sf: [??߇d|_`жö:sc t\=LӍY|,^x~1K&a%Ae$*[W/b>:rվ[hGc ?_V>'ߕw%{]~Wߕw%2<#IENDB`code-b3b483e0fd5e/doc/images/logo-software-carpentry-standard.png0000644000000000000000000003147407437047562023154 0ustar 00000000000000PNG  IHDR,JrPLTEͲ򜠤O<ӆ߿wggeDCB./,##!Prsq{}}VWUIVXG/U IDATx]{b}RiUJZ-.,A@{N#$Ïnǥk5D'@5J`5GXhqt*x^È7U"HᠩB[XV1.ͳq*u] BHh+c@ l1Il]q(8-U9$@ U*FbLūM&GߏUEHk@ !`g9.Pզ$!.ĸ5jKHVj]P/F(뢵ʩtg! A!MMa=Th4u3tA†X5*S$qynq/" X] ?J,9:k zE4u5v`5b| $˃EmK]L $Th[rhj4ckʫf,)X,E4ދWIYb01rU1̳|3ӡ.φBg1g("|D}j?e9#C7Y^ב#_+z[Xh`j+9-ߗwNvKz9XuI 4ꧮ$禑(庖9oM%bHD(/I3"R_})au0QUtjy\ݭV>#쬝2XNu8gV{zal6;ZeQǪ>uIwgpc ˋ V>`%ץ㸫%`|?cG:y]5nB(J,uq%b{{P"=tjOmpH|-Yn M96 CֹXJŒ%XჷFf ;|_BiGš\ %5T$ոX́*ilMy4<Z#gL0tz݊uGB<ëbZ&[AeU1Vm#0\Xo_qq3 wW7W`VofԈJu enhMwۃ `Cd,^Yi5m# !‚X X66ζ.)*U=R`px˫Fym]/.[zUlQjCo +I)ǿ% J#3Ib') %F`VS,YX x2^AΊ0Io~/NՋC$Ya^VZԇm.+xcѦEFdZЧa[L$3J |>58N\M%+hmz_VCʂHbt6"tᡤaXK(DOm/LοY_nڷ.)'O^Xރ+1ܔeq<ՉJ`X>Q`ֹB}!Z]RIԪA.Ɣ5n@ݠ+dU(^!$zAӝ3Z !U t ڄ$hĪmdx ٧AoMR'>*'PV$jXdғRӧ קϔ@G)rrmQ0 ͋ે;p>)?SEh8X#fU3$ 8Ø$l^r`{>YQ֣)rk57k90_Zm=H+U1fV>>m$F$"gh WG0-C]b_F \M* SH싓0pf~ MO.Q3Zoě쎣"A[Ug|f"J8nMEa,xrv]]کh=>ulLGaJ  T֨x0:zYz _Sp~ r>ekYr q4 iގNJBj\*ab9ZHFk\B֯T{=gxl-xB1ɼHū"tH;D)DVWי)k䞋e֝;[`nmc'\hY(Rt{k~(WM>zXGX=$EۻE +{^^~r +jcMR<ãtUjg5Ӱ8_M[YemgmXrT ֮,H-@\f-IY'̍~軧;KΒ`s~zKԖ[`QLi,KI=2slm>g%,M bQVk>94M8= ^ >8eFscj39 ݈lz`,eRGaxhӺ<|-!qD)t5P,'1L6ގ/,"jY3Ȍ g-.: Xb>͉g?fqQ&I=`LrwtVC(Cxzw`^HvGr1Kl3ŭ_VxfU M(҂GF31|dZ }[`EHX*FwJibw`wXxi%H^ wy4JAL+cVdgr;/4"Mc2P)=X>Xdž;I1hٿ`iH_("xA׊2=ʶ !`ʹOЏc)3e15-."L}Tخh7^{iKΚ&`2A +"]~1a7!Uh3BOцXH|0++*u0MVse;*6.\`yŨqOX>M}2~*yקk~/;_묎D\ M,yVk +/Jt\Z>8&Np%Zִ{$9kTf?w_g^)ʛaX^io h'qm;X. ? N> ,(W`_qkғseHO e( lEKu j BYz}2 ch[~lrNS/ZFX&Qƞ Kg ,d.0JJ9 w rZ~Agߴ|N O7ʿ冱i$:zz֣bx7qOg:k.`}֒vPjKS :dVWg;Cj<~C V/XX-GgyJgC[PIU:Xǰ{=HY"g:U6[&Cfr^ߐ'RÆ\ud>՜ zyv'%ٞ'v,-7ˤX\3J%gboY ` HZwSh,G#LyOw3tV=[(J+twqT|GvXViuuշۆG\E͇%Ro]:?o7FaY!ꆙcLhËyFXv T͆g<9i0X .ga|N)UQR?L+t/b5!O2lYgrF ] +(G.50>R,\h.&DW8+_v3Y.f5DwfTP weoDzvwYWOfظk*İh\.bձJo';lM#4d!Ialg*zuU MGZp_xA﷯)a~?i>Ul/Qm7݋i,R1IXsխ8 ˔hpWIasޔv1K9Xs4k4G7@oeͮ+#G;HivHxVT,nd }.Pcquuv:X<53Lur^UX@ YLQm1bgd]m7BjDHqY0{~z,WMRDAֻ2Z]u 520dsvdfyé: y+ "Xf[?U;e0:P@ZVUc,O9fˮ|Ȕc d城,rC\,U$:gӧG,]F F/ *Q?@q֕C]w19Hā'-WZ O5'Y΃ bx0_-hS[tAN,fMKjզU!\ ыgˀ)O{0:4odvV3%AɰzEpu=+IDATLؙVj'඿Y)gE7|$y'Jq@I`R c Q+YRhK"ܬ\+&ܸ fqUkHv_c.5ͪ*F% UE&UU%llUe{J{=GeYpS[|a"okq ac.r| #UiK4L"Srj6VEohy@"R* Tސ/RTh$n'Wa|QRYwI<ᝌ5cOrO&gaSR1!NeؗkYUI X9qP$;A,MgY]1<< :K^[:bWۥク4Y0<ï} 9?R鬦 L%:Oڍ8Uq 5Sn6db+(ΆY>ĪvNcfU]5*YX;OerΒ߷2g/}UAE*}Wp' 6ejZ}V=;vK,q q $0P>U^ I֝VΒ$ic١G( |M(H&Rd $߰)T#a@!/Spoi9a1"C'//ܧ.&E ,ыgU<7+6:KRȏ#f~\KQ,J 5)URLgUUۭj=;6 .8qۢtDNJTHUgULVeYdRu͓P?sϪ8nqsna+_?`X?(A)3s4/|z73?(cMtWc,o~xsSYMU/`aI Ì7r<(my(z~JnDyv| 7o0?܌Ǘ0V,س֞H)Ϗ.Xmx?I_, GqGz^,r{}h\G x* }7$ӾK~~BĿL XqV0-Cܙz@ ES+³-stL3&E· |~4ԌRkL\3Im#<~7 n5ƴf! rL42S +WGx$L5pP?ݶM3=BoSc Iq" ρNo`4>K\.8\P7a.?>?Ga>h!*Rj5lvx7MM=_hC$Rryhe Ob`%=?еMܞӼm2-$;ih8v'`GB e)bcۣ+aΈØ-ǞV{=EAj-f 3W$i0z=`n:Z78ajqA,<߉:{sMcT,7BK$=z,P@i!&5R3x<ʉGc؁LHR tGw `X偬$@5w 1X Gf"E ԏ} 6!wu#`$~ < Mpcx@~HϷ 3AOSt}u1FQPL/\&R>"ͱ0oH]7D\7??x`iڜjBV6> B7D4|#'Z{(f\oɝo|XUf;V8NC4Ԑ=~@r']S*=_@^ě晟g9n.*vs~nnnI9l$1H|z¯yIA~$\œ㯖Q?< *:SpغǛǥK' C/>m}ǛbRni)aˈ  M Ժy'I^Fvvi~ t`D{_<'d!nCXx^n*aPX'5m-J:ζ}'hlhU.t6bMHnMAbpxTt`+ Nv LmbkK7v,U9#%˃]"w|{y@sl^$07v5 {sY$! 0:2XOEX8g?a>R?)!^7ݲo zms(=,,tم[_)A~P!k6<IENDB`code-b3b483e0fd5e/doc/images/roundup-1.png0000644000000000000000000006340107437047562016406 0ustar 00000000000000PNG  IHDR}0PLTE7S ){BF " Df4B$@#q:+v@1I}}}d{{{/Gwww7RJks{s izzzU >\ppplll Cd0Ab*ZZZLLL/FJ)BBB@@@>>>d4N4N/~;X 000@`...>^'&&&G'!Y1'k:%g8.}D BBk*u@cskF IDATxeGyXvi*AC؉O 0#;Qh&Ѓр^kڑmtQqZAŃҺ@h?QUߣΩsN{My㫪6B1^xB(Tžb7?HSʬ(" M:_k_<Rl(tjyվ+S9[$H/=O.:о Eاڧȉ~ϒ0=&C}>Kīl)y}k&k'ԫkHE)D7>YCy<$a-= !Y&"i]R6.ka RR>  Ywi)i`>VF6$  t$̢ !Uo@`h'`T8/b5m@؋9rAJX[.j`hy<}e,5'wGdQ-ҾOE)gQ c"iם| ¾=c+EF>t跿o\-¡ E](Z(Kxj:)>^gǥ߫ Ų`s }:U3s4mSRdU+"hhkD{lfa(bu"ݶ:χ4}D N;Wld_cϖJ#`&Z;<)c"ܶ:?~K0`}<ɮmd2&Xn3EZZ.=.yup/ޥ^*T!e_9a4QRߔxxBu}X{džOf{:OQ;r3Q싐Quג}6̾q}-Ob!>M$evrAHV5BDב}C\FX vkWI\"Vx)0Vg;^}ݶ*Ϛp:BXғ]qU}rطaI,F>>JAO1TAO1TAO1T!}g׾kx7+M]!AOC4-E%ĦL&,Zj_KaiM^Ίr0u/}هEZΊro4Ju=ja>վ<4寲omѝ;G9nU˨OT/^AO?} X+G5rܧ/=+&վ6:z|~pppg踈)m46PsV @!WjCgΕ飗 );a$bq)b"\ ~T=oH:hy\[ɲ["rVqY';:8qT˂|Fs%y 7zriq"Qe; ?[ߺU(_~R n}q+ Px~+̾Frk~pRЊjC![m>?<=syw̵g}+¾|u~zt&_A#+~h訦B|q{ރRʞ7}w]nu:~-|~D/WQo54=Y=\e;=w4qKQ띂s?SA3C jn֭;VMG PE^Ю`Pr*] }S7}Ƀ+38W(vN/Яо[Z4oQŴ2}i_aW >NwfAŠW >USM<%X&ǞYWKg|N_ȜAʸcȾ)wT}w*|#ŀ׾z$dUσLE1bɚR.4Gnv K~lrTה,ן}9G_~hK|b_^(_y,7]~fGg_52VA-yW85sǪN ("߁`ŸoU+jpП}/Hr/Cw6FA6ƶ7i_Ic3.#$vOfd-sr3kJUN!k5?䆳 ӾB؏}\(GdtŹr2oaQ>R#xeGVi9+/v*璼p`^*Uϯ4fM1Ŕ9nA#s,ŔXw~uӾ+l w*}~s}>r sp8w-b_t7Ek׆i_ŋFYاя}W w~|'XI>4Tnj)>-b۞s5]ǭ$]1O'J)'+E}\<h>wI>7-bs}%/x]dr¾w=*&>B>Oʉܾ{Wjݿ!ڇn9޾J(ՓU)h %+2cԾc>[Lu$WZ^S҉~ ~OwEsc5nGmg 7e-^9>o :/͚2b9Cξ{ĒKDu,ț6AȫmԾikay߆o _}tԾW fM!ľfd⍷!}qM2f9+R C}W]vM7+{3.?~IڧPD̆f\woA&$S("Wm+~`PΪ}!fW߮^Bƙqzڧɾ׮(T=մvf)\=>>E7HC gPyL>>E7ݬ9Vuż꣕]-d<>>E7+|p\f1wњ^.KѾ4xw ]Koe[/@%hSß5cB|ze.KҾ/(6Ⱦw-ynدqYo:(pMv"WnvykH*\lgnD٧ڧhF3ʯ̸Z/wߨ.'pU}̾G9n)s`X/+_-T]6zކ߅ja}rOO{t޾߸vUz)l >lKЌ,$*ha=7+oE撑TAza^e\Cc!?r":Q[pv}یjiťI}[?ݦ>.rFGξeǵ#TqZ }SutW rҲ>$vhC0ri\mCWLzgRh 8,omD nK,7WoVKՋ0f-pv =}qc<_8< ܑh9h ӾCRHAԊʾ }uG[5(ka>mC?P/t>/4/v"i^mB^jY<޵3 { b}`c?4v>Hd*p)#}o] }OUStF:6ƪ)+$3Ŧ`<}S{LOE MRa芁SSTӾPӾ ūM]%U_^U(*yAO1B7W(FXn־kLpڧX"ΞīU>QW)TAžuڧXBSS,%*ҹ >Ųbjb9(HWqjbOO=K7jb((wVOO7mޫ:KYo^ODPO\^=US,!)>t}; E2ٗ}SGNPSL>tPSL>tPSL>tPSL>tPSL>tPSL>tPSL>tPSL>tPSL>tPSL>tP2+@ڷeÿ/V}ڷS5#~kS2_u?$92F\|%KVoQ/?DOJ,/+aD8W^yU=_W&SrFD@,KULQinGѾ ΋_w~O~쒟w\zQ"*Gx…J[\Qo8TV⏊gg #^}/X. jIL9@GE7-UHR *_~ -sť}N<z[}[ݫ}Rٗ /wE:Ԕ)OT=l˵/a߅ _|k_[(..\S "j 69*Z~:>IąI/^xSw[?~A{\ P]ﰙmPl8n6|&&3w$N#<)⃎{mokŲ׿Ɖ~KY6[?o=xwǞϸ/L)e;;:>sj5js ~ve4m{M/])FTpc9*b>"vv \w/GĉIZZ&ǎ`ӎL7}2/0]Zr{Kݻ…N˧}6s6>z5}! /NJG?w˿Zv 9;|Ÿŋww]m}Cg4Gmfsp7u7\ ].v}~wcLp5-tPSL>E_GZPS'^yO|>EoT@O\z_y3^O6ڧ艏Ƞv[T[nDzw@}vnZ0^4Єjz`}:,03*~?Ltg>:=_ 6|x~??~O Ͼ{፟' Wo]P%b_+|=Ix_q:?:|{Ղjz#W0K~å_ 7ϛc?' {3v5ڷ]HE' /U!ew{ z"y_9[tO?O@3+o#?Wo_7 ~l[) s<-udi{Ĥ{KoW_|SN>P^/qeU(9P' 1{$,MUŴԬ*Mkn)nF y÷}YݻVys=}WO 3'Q6=Mds,\L>GSg3fDF4ڔPUj )Gje *./~njgkRK$bTlPZ*KJXSKsuak\>=r.SPG:%sfk'4j_E+ VSKsuaCyǛ\/|[|:pcL6L8*L fbq>t~ňj.}+=)F]o/2)06W;kڧH¥'_P? ((wVOOш_qo~; ?}oyׯ?H_z>E.}?{z?~s~ݟx3K/(VاڧhBΟghcj+^|hZo__O4H:ײgv.Z|3JtnВ>"s*_w=bhue5}YԗE[<. v<e]%c?7~6$lp0rFwTH[*^"p${Ϳ#1Csͳ)/ `Ha_ΘF%"þ}͟<0+\Ͽt>حHB}ٌ.c嘔D&k+j3kjM55E +>??oOFY17[}Sv>\ۅ(\c?Bc#kmLRDzN #Ѭꑒ-=hB^gVbYKsD Ʒ~{F<_LY|gg_7"d>x|U.b?#O 5yNdI#r74֫"Ťc-׾ߙϿ|t!@s{8|׸L:wi r,R o)Ka4&Z.L:mj<> ; IDATo>GoC_;b}}f[zg@9@GĿ|.7\`k68^e Ia!J53|3|l:xDF&OZoc~67p1Jͱ<|sZŶH왂_~cW#@ENcGVyalcJt &I$lc-ڧXl)}ڧ E2ٗ}SGNPSL>tPSL>tPSL>tPSL>tPSL>tPSL>tPSL>tPSLP4JbKY^l)(Fk)z#ځ}ҨA{۸o#[M/K׈&Brk_ Vߧԣ׆Z]D\`s}ް|`FMn&ùFzЬIg>;%  G1hKWB]TC",> R c&^zQ6;ʾ>>fO}R={de_l|&>hk2=e%M_灸Nr🄏]jlYfu,* ~ZG`8۱<ٵo襫Cn[B{o5׫OW"rk߳ E2rk "}[nbڧ}9_cnOu몹`nuUqΝ`}G.U8>dvV>SkǾgֱ~ ݍj_N1ݜoNg}g{O{^mq~6UˏO 7szRˍK}$έLR%ys^Ų1}%b/TAO1rkߟ(ȭ}d־ۣX'־Je}oB/S65JMlѿijTÊ*ūTse; fec>3@DĜ[ .C}ᇍ,a&`PGd:˭RE^Ӫ$T& 7)mjFlhŀ܍5r `kVкVH߰ OkZJq֧Q sن}=?H_61ԚLH^&YFeQAP .|*"4D2K\o~/.^nYH?GA[K[G O2G|и+U#e5 +ʼnRS!]a̟Ag +G*dg~mC?ks]O0i%>QW+>_ˍX1s >`!4#P88fA.t'>|y'c d$}Kľ rHt8Xݸ&e ^DWu=/ G18e"'g#qe$1:Lѵ֋^ @\v -0PA]Q<&>O"{(Isrku,Wfz^lkI"3 D61F Lό CyHqe  )e&`p4âHYjXgzLV4eǙڷʀ$kW\k!OՔ7`)9KnkX.SZ;Pd /j)9Vi4n-Ц^fjo̲]ڧX-l)V }(tdpMјFyjTӦlq-(6@zjn+2**y`y5v+t)|lی>w8tG9>R ѓ^^&u2Z X}L.X{C)EEh"["vk}/)r1r ޣS&} k}[=]Ee_>>ec c7$$ՠ? С >o#n+]e"iGjCpV}}Kö3e - Sc@/ 6<rkBHFn훺=uBnU(-W'-Y6W9lf3f 4R+heiO~8WvF \eX0cS%Wnɛ[ ÌeH˛Wc[ohg_ 6?(B[ {'J%kBPyFLTM46>g2thyHo6[fe "+Zs< hrLs'D‷`= }CۜhF>;`7Ku8{-ă%da K$m릪'W՚f\q2M_7+CE䉳o!9Y=*ыh"Rq g a8IWb}g`>@g)(>'2L&D^AEbSLa5sjWe:Q=wE7Pf~찚* >24ǁL\eKoл۲ʾ˟Cl3]}f]78ʾʮ| Ž<ޅ[^&F]J rkHkӉEjrٲMy3jX2`lkw J]jy8„+W( NB&c!X0/4YL+=[4`"L4#h_pnk>t(o"LMn>)0qF,7ٷXBT\Sυ RO? oCоx}i1؇lV0@-cMŸ4d X2?u&Ig`[_G";SwX-x'ԏ}ޒ aR{H}(exڣCU^.:yV37 lXq Â>h0MyY1*eB=U kAЏ Ycy3GJ+lwvEcI) 2Nt=2OϦNV X,4Q4/ªԍ 8-X)XPm{X7`jS"MejզFk_aP߀ժM>jcOAy3J܆5|e@*rƫ:ajM"O4MbooZLbMHFD{Q7*RKkoS, ί}T hH[oYIw{M`_j ٵ~_yv#y b+R&x?}L}J]6[;X`MQQ=.r5ma{b7>e>*e3惙?;* ʙ_gy1}UlwsbAC4Oih y0U} 7<;A/zѾٌw3^\c9}p' `i[qK*du~/Bicv)K4qᲘ~m%vm=ᨣw2}iL} 58GA}&c:> оC.,GO=ȣzD0(hbKR9QN'DWޕ}{…>LK`3s7suom HL}.e|ER(ɢmX!Z0F^ڌw9VqFc,݌CZnbbw ܰ OD]: 44X/KpΡ%kY0j1):b-T&r@S[[U([n(PSL7u{>tP umb#mskTX//, s|Pڗ1m/SKD3H;oTrc*}fo[GP/3 Gg[SK@c;هcgUr;vϚ~WlȬc>gת}C缊aUSL>tȭ}P$#*ȭ}SGNȮ}ׯ_-u,?@ccX@ j(b+8O7JgsȐN! }!+e8i˾L֗>/8IKƾ$aƒ^Flfߒczia%?Nm8h{=07ձ b:C}cz]M2kXk@X TV?Di®]2(* ~ #k57;EI;f5'kF\>wv9:HQ{$p KtVGuI!W,.|g6&NN%}9)mϾ؉:emξSA@dx\NSi#|Q7VBAVlӥx4]Ez^@gg9$%Ĩl %ax<9wŸ;}Yil? ~/[ۜ}}^Sy(*E<}׵Ь΁]m;|rI}LJgíS6]3˹Ҝ%aNX)1G=bgSA2w}n)6̖rs,m&>b3;f>%SwfAflB'@ȧT6 3HDrIj4āuة(USbm&ZSjȯ}&KauHxC,ٵoh9k^)CaunkH 1KnW([nb0af.`UIdPe[5i*0VckaZifʱE\gJ*?G0Ol'AZwY3vea.:4ki>gd>*e=/ynqp~q:}OmI>^ 6/ѾjcߌoR @)ϒطOr3:QJӼĭ * ciٱ>Ϭ Z؇YG']ٷF`'j j_xcs#O0}ډ}L5o}Ӹ@s)W\]vrlHlL:$)'b& YW?>Bl@|9i>d>:͸Z87 7@:X}LgjHA@9LO3۫k/iwy>8mςoա7fɂӾ=ucYhbe}ڧX}vX2mqY6R{lpoCs.3hM5ȯ}vXUƧ_NEG/,E~Êؗ\D("aƾ]"a9hC7Jх_{B*`k̘ku]& _Q%kWɯnf~n*>Nm7Sy~u`x 7Q$J7L21Ԃ՘:ѾVm##J~ur`DC'3"9"Zn?f[ډ`,K"}};ɳ0zm!G,}SEM>p}1(D G=>XX+ؗ>bMXwwXnTO&%>^>UN=ӆN!M^<7 -\N&d׾.;6LdqhөQ`6h_Ȅ%2" -[gIniYu3kY{9Vp缊DtgOr^N7H1VU:{7vaY1Ѭc]Oȭ}SGNȭ}4\淹v¶9z\f` ?KW4$(cKc_nﴅ}C-Ͼq_ŷ%p Md_wþ̘TN7;meSG0~`_ﾠ cuL|g f_`1V!+& %ݞ:5vãhy@of(}8u~y xrE4p ۑN=~@@(iWg7y>;kbSw(?b3uJsw}&)(I$u@)) :AoH>9E*ӴqG{8-G\@{1!w ]=Yxx4r-v; :RK2\=@pAfxvBϳNi;oI}dTI![ENg'n.y47pfKet)]&4 ľ%{6ҴL2͹[NO\, m)N'i)St=aIEMyOiC]I`ӱkEs䪡orAflnX"J/g7PVg[C۳DHFn훺=uBn'噽M,sC λEl7dK33!ɒZn׾oiw :'|e_Ӄ[2K2?d_긯 Q-}lG⥙2EUl.Zd$L8_ro ҝ$&vliJ0[Wbbְ5Ek=OȆ3+Y1_uaʈ8v#O'$;P 9y',)+K'HIA`QaǖƼƼ)`Ѣ@,7'F>:pso"?ʳ~s'NB-} !Kl) q"A87GbkN:Fp.TvWrbLqrg' qIpP f0?e;@^ZA8}*]g # Fоa:@ٱ/M |'D=pDGc_Rrd(WðӬ:3,{bt*>p> fK hŸwy m>άHDnٵe|ξ`l);}tLv4cbܚ?A['~u\~}ªrBkƝ\ᕬȯ} pȭ}Sg˭jcv-ڧ}!7΂bdl}ʾĺk}a}fz+',hٕV`0fҭCKDׯ'X;f/05ٓ}b;P30F16K}k> 7(yɞ5I1^C2X e`OAn[ Gn훺=uBn@ٿ4~L p5TFStBk_0t4KaB@}rk_u^FR.wSٗ`#x5xR D~wX!jݣ0O (57rĆ0%?$F *񪞞zvTh-e\H\?0_ yqho|pJ(|k}j: U) /=BDz-DH}GbN yDxMX̜-|`^~~P{++M;gJ>G'P>\rhB$N?J>)0qF-*5F`ݮ}Dځ}®`^?aAc2_ ǚ+':+Dl'O;X> X1@==/0%t =u,pw(G} IDATi}HWI62:Sb[;/TxM#Id:EK@-E_VsjK] N[ԋVAF>}3/J{o 0qRdt>vl% *jNSAlQ7C vaEjyzjSZg)o#P:ρPE*X15*w}KOi@ sJΌq>|Q^ 4˸Dmek`Lk/@  C}4H:@}#k%Pk;;Gw+}~6g>כz¡xchUtw Ci|J q wUm&2:s'M t8"ὑ]og{\Nq*4[(ȭ}SGNA9zQ̱q7P ]#V0xb1yj043rU_O:͸ȷL\6w$ I#q}% MW1Ι80EM3[dBꒋr :@I+"aVIuϯ}-/POu ݿj"qcڧ}05rs|;\pSg+yaq5yk_+Ηq{\lϐ 6V mbQLyqhաhHIl2/׺*>hKP1X0kOarDU֦JZ 2$;acqhy<`@×h26bwXC<;~…}; WGwobkw)"t2՟`Md"%!A_=`^]fw7a1Qp-pW`Z"Q[>1£׼Êy5of'4s&-fc>sB!򑴯yՌv^݇VI,v m["AN%QrF!8=Id4vDXV$$ۊ vr |IDs˼, ƪFA6ʾD~B/<a} E2rkQFоr:?3~uط;/FF-sƲ5XlAgֶʆz}ІgVww;MMt;x<\@s`J \,17,^¨WX>&Dk.i²PShaѾ}2K臭.r@}CP%fh#ؗT *&vZGO2`=cAF7q7>9c?d}> ge11Aā ܈f Fڗ!Or /<@@ k]יcYY'CK5i3ƘV\YDxڋm$:ޑf?؋g8ƚ HL}.el$gcCJ E|}lǬ/ H9G|:LT* q:y';;0{6l:|6o+о8 x>29Or!)*l} 6}ڷ$dOf}PSL>qxqҡNmվg܂4 pmվf+>\_t͔/0IYQ`/Z ,چL-dX{#8w91q},̅6}x4(>Jon"6S]oEW?z(A~Ԏ #}s1J>1e۪\rmX%C;6";s&+T׾4$}IM79C3\M־"o( ٵD'iV0aO  HT,1W'0~QBd֑} 5/wb~O ,#IВ0E$0%:h>d`* RX{T3cxCrF0gtQZ;d* 憰3!* 쎅}u#Y#Z G?_`avlJz,7-`o0-R3HZ4>3]9aVe0jCN:g1OGcӒ,.mHN{F!'[*|"Lz>}fsx>|,gs%'q'Vm؇,hN,y$DlpDW;aOue_q_ O#>VHb-OZ: ^p}L:H[yjɱj{ ءDݹqçjISqp[0I=).+,}|F,[h=KM%e>>iYtd3u4CQqq@ -2osĔraD,E omx-IڧH޶ٵO2ZM% >tPSL׺j{  |#44:C )7h }#<. >&9!'`dxUF}6AqD$>|@,Dqr>agƜUB;N>;w y!OnPB~0hfzL;:"%ʷǶf ?ӒM, ;'Ĵ)exV5v~B1)hoP$#M:!USE}%dl@Q#sy$! aFEFоz G>Cit'e[g` A(mjR}fsx0s¼G涢?`! f"/m#hHYdYr!Kivyi,HJE}nQWc}@OhlgD&8| #XXٵ*Ef:'bRKF/ālkj70TFR;`@aڧP")PSLBwCHjb:־ۣX')jh0nPnjX(|0 ._bjho`kP?T"n {^ ls.zM2j7jߨhyWj}٧ : jr@a}c]dU`kz.@O x9bynUAO1rkߟ(ȭ}{ E2rkQFоEyW̑Ę@(pUX[}7 04N؆W3 MM@X)ٗ}5} DKA}cD2Y;*iΛQ,Qx*YCWb,Օ H&&_ZՕkS΍Gl6ñdaua@ukSE̲G\6mnh w}6ak( PY_9c$0#,KXksb,>;Dž}jUg0>hojOP6}6 hk"g)g-Q%oOYtbR>Os"W\\_q?0J: gp'r,&9™O6/3kkf\g_fLR ڳZ2#T0ri\fogL?PG`3"m֛j+oվ>XՁjb:)ڗê:aC^]ܐ^z&õkp q' 8ʄڗ*XF1eb!= j }" h>ʾ叏ImH2#%X۳JeBͰ("8p<HX`Rjn|ٟP;clλ*;c6j-,a]#h*a]ֻ#6[]ZpS46[G6kMxݦ+m_1]Y>_ X\nr]t㓮tGտo5p%ʾHD۲B0VFĢ] `l&ڬz`dєwK(g_jȤk0 #k֗kxA;. u=wazGޮaEMbv.Umwd"U+ޤ]&XaϊoٷFR+y+hɽy+U. VW$$3] #;7yط'!Dc0+4p'FvĪ$,X/&X{Zf>ar/W{G'cߞ0BȶmE:扰V1nlJ}Y^;:?~Fy W}O}@}^i91mUfv׳[ѱ6&Tr!n vZ}TN+ t J^z>?-ȯcXi9]mUd k.M eMW t"˺TuR#{67DbʡU I8\Oo3y.v/b/mh74Ev8>c^ bee^)jb:} OCx F6[teF>dCrٗ0x |U>ٷd(]]s+I>+F tެTpoW`m^4H<\^lhȋUcì=˘3oJ`ʾ "}+ӹrR R& 祕F42xCavXV ?bۣ oo/Dޞ{E^9= Ie~*ˡZ2/ rb,>u,obVhD=}(9>Z@ԔQ+jﰊ+"}i C%eշg׌Ȯ}]*bqdgwуEnwE*5 I}r y]h8|I*Eĝٵj 1l 6/JSGuʷ*E,Q,E(10E~sXȯ}LժAʾVj[8]jn:V6cc;OJSFоn%phzqFYX-L2h/, B;y–07%aM+¾h h_V{}5ox!;Td[ǐ7 5H>=G`M!qh_VE}eu1 ?^$v|\WǐuyVoUK+qLaŽgo|Y0.؇DI7}x.ȋ/i;X'R>`)va&!6}6j%vX%Ke7}zGV,'}{Ԧ;VO8!/k_Vb^+ H1ov+6Qtf3ط;:޴VtQܞ @dvGq6{5:usm*ZμYg}S@ٷ wȭ} E2rkQFоr;3nu0*:虼cٌY]{$%zޱYG_ J0#Wo3v)e>a_0cS%BocD"|fcP6`5ؗ7o7@ Bvfy.m =yNT 8wsX~kvY dWX*ԈT™~i"{Z7RGAvt2þc}ϥ ?ӯs'؅]g صO&1. =84ׅe؅O K'\*>C.}f&ۥuP.1CM, 2pFI[:ұy%] `Iz"Pr`,W>?aY:}]Zp,`. dQ59}~ fk_lt>?F}샛}L@8x'3a\mEɩ sE&d׾ˮ kyh/;ǝSC]T.)a1 4G|Wq`8ftJN.1<@x4 sD]3K ԗīY/Ђ-%kIDK_mڷy"9*}1J\|IDATڗ6:l_,eW^n)FB8w劽nSt%jh/]W8Bn褖nCKoݔ<0V]I.ҵ"u<\I{; Q, G ,y "yξqe^}fF c_I+5UbXd=wԾuGdY4%][ub-Y+f ՙ V-E5]raY}]K97#X=+odQQy9C4ŦHҙ} ߚٷUEF\qC1lRK~޴>K:n[.'&+>^ TG2;7axf&`a^b>[PhB/O<W2ڧX"J+Pbb9(}}ոUbI8*KzB1mwb_@5s)VmwLJq++q;:.*3|([bq#d_P*Y_xᅃ#eX8o*ޕ;R_/dj;@76}ظR[W8{?zQ d߱U3kWR ՃȾ+~5}}vQ\7.6}dž|}|iW*+̏쐵 ɾ~GN궶i+WMy ;ʾQ+Eٞ׵eվ~y5T du6֚k>VTek}vYRT/-/UBр6 >b0$SLB4{MX"R |UP !g}>g}>5C A>_> \}_$ sŞck} k0Z7`! 5o|Ch Bk0Z7`^Lt쥗dt#udK_ڵ^ޅ(}R[RX -cKw ݾ^{׭pWC8vrݺ+T|lepkwu^ڏRXtҭ>c[)3ҽ+׏{7F?rWN]zx@|6dLw_SN+tV|C^ܫ.ߊ_鏑~>//?Eؾykw{>_}g\_~}{ySnv[9yI=\&t=F(+pPc'~*kWܭlOӏ{Տ_P|;=~_:(cr>H{]0o$*6H7JN{6l,9)݈dƍ%{J"={ƉyyyyǎI7m+9 ~h%uqXf>jJR(;n?ӏ秣0 ]w]-*5cEW籒PRRAI@`V ?zLhr)w7<jU }Cᤴ$(e߰7RX t+F0?7ބ-qr_6w߼nO`w ;{ nv%DձcΏRaUw77܉`>|r|ElH_"A\b ٓWQrBZ"-ِw?_I6ݰH%y_lpR*!MQDY֗ߌ 2 }Ì<ػ_~ʳ`FEzfܯa[n]^fϞ "/1++N9"'={ 0;7C0`HjieN!D"=w'^x/oId-չ4ʗ_E/OW~S@g~/_{OKݰ}|o󗟟"?ŝ9|ne-1`=ÄdcƓғ'|# 3f)fT=`qJ6z`ZrK6ܟWSٓW@X)]=1OZ;]R')tQdDá-fX_y?}ӯ<l/G~g˻(/S#VS~_Rfqu^|W_ܿx "G0K{Uh㻁HJ| OZ d4>"捇Aѫ B K@!\w?9xIƍs |죒 g%y ? 2xjdU*g_}{Q߱[闏LG#H?wKWoy;^;y,\v0 *.tvo;yzJQ!n8YB1@Ǥ޿ 9[G^z(d/p!`\`{|E|JheЅ@(V'*Һ] ߦdU5skt-F7*Di U!w rpnϧt_5W`0>111>X"*vM3ؾ5WAjh(˃5K`^*|wsj*)oI}__fߵ opJu+$A&ɽʈ~Kj;lWi.'\{!«s0dr*BYI|ƙxFvW fǝiU&%:aM(T/1 X'gWy|!v"?#DCoR7e50Jh)B'![ސ_^N;!Lt)Xpn{JmXNIMZ1r_kۅe*|{92j%s[5|Y2#qI)l0K"*9Z:^\ztDٴ6 Hr(j'6`QCٚ߮JJ-(yhOT:}6gbJOV远Pf+>nχav3 N|\X^0]h%qeAեa;DHh$ 6 Bx%sT֘AϸmA;ʫC`֜ 3񄐠`.WR0gs6`kc`F&94! #•SŻJ:IRLN>ߍaBm't͐EY=.ʲr0`]R9?j ćl(]绣0C f>:†yS\NAX'60FFCB3muiyQiCF))iQmᄠGLk%|(נ'qqe`QHìvn.ƍ+JPR?*p`3W cFŲ0/;`` }!0a5C;)У*قB CZ G6q 9F64%\%Ԏrk0Ƿ&^MUf"gr s0r"s`S҆E^2ȏAІ^E( # .pPMA[7ZAh&FfR1Z:g]v\dk1s\⯮*Py,qqmWXyhaqWXSͅ0W^k0Wrbܲлѕ3q…Cզm4 ;}ʉ65:'6gn1 2,_ٍx]r|_:.qqѩVDȭ<9r.JB:D >[vIwa6tXhE "\sء Z}(X\YMͅ} ϹOp5i|8 0q%:/s1'xaMBqtz8 eJߒg %YFR.cǐī#j't-c+ʱHqgVBvph3*zBkwa|7noU܉\G n>A̙ƷbAO |·gQ:*}B UqC5 Vw;FD;碞|!ΧFrkA綷rJOBZA?D>e<*wg &s0SgA0^ br藞/kƇaFl0eb; YY#l p8hk'A_v mbe9l&ԩVh+//,/p1_fg3n><f3`N]f '#hm\Á-,p[}gm\npl-8(N15m5Bnffښ]l/1~bftAT0:uuSZhlAl $9ݭvw+uN_aF=>!hłmmBX9 s1t;jBBH܆a?;)Ą0L!m4>`[s]lpi6mBt< E5gl QY-/*r55`bPN`x 309 q H)||)vO}h* X6; {Wo4nz fgcn#v. 9>DD _(1',x>,Iq Z5Xpn;,=Z%JpkrK PX6Dl+A dRk5|ʔ%ZG"s{[T"Ol R ``A- 1nyEOntKYNt_p aRR.:A ǖtQؓX*!Gץjzs܄HD9Mԉ+zEI})A4P=q&#TtHrVT>)4<{IoO7 wSLw|ӧpUg도_Yv?2/L+j#=F|bݽmڱ]ʁMHu]\1~?̿Ma]j4W0Qٯ+˕b`T򃙗>:^!#w=MGx(<}[~ewȿȿPv_{w3WT^yrA+_\M];}|~ 8 s_3+<3G}(ȕRڱpt0ݻ`/=n3/~0 ~qyǑݗzj|fMwOU0߫fUO9rgm2.ݕ\~P+b42]ʯM4+S͎raǑ /ߕ̿aJf?͗=^0{Uih~4n샟]-j3P랺ru>t}!f7#GVS]x+`. { JH܎JG.ĩ23? gwU)Ԯ/LZʚě hab|vvk{v[Gb_^?At,Rr\$U'+oio[_B0V__QM-*Moi]|?Ry0o@m/p[C.p[ZETя>iil`1i?FKS{^ȥ&32 Ԥ1r2\dZ*ŀJrl weK2{=#?ԚQfM /ѝW18#CH nW>-L!˚+`2 z i,g9#24O5y{ FYOW(UW2)^PY'ͷ}`bS{ƠWfv0b0sȡ!@џ#" R1k&ұFP9/V+Ҏ0Sr1 `uȂ泺z"C *(..`~fqAx4q74*^c@ }yI1/8V2DfXY,N5xHE?A0AqYAsP}A,VUd3V\V\z& ' s p1 ez-0zA+ Ҽ)̡b?I%04LNC Wz8VQ8w\VuuBZcnLs)3(QPȩ?7CyVVK1O'EsdW tPoo/#Y,:,MSi ioqn(&?KV72G IKR Hŝs^o&Y2`L 2MP񦤤LqfoPژxc9F5RJi^4iۛff/c{+( "F^텴_hAZm}TٜR|fKTBV5ȔjS)ir0Ռ4s}Y ԁxey@_(ƚC9ԥUfF5(8IRE$RPbBS\gz@I9Y!B9c6ZƀaZ&\O*~߫)c^<2rRM^f&{L ^\BQKfBO)9?9E=lY%Is# I fb%ʌVT>BQ~A&R@WrD^$f4qPPڛ&jN#E`a7@͊zQA5p(fTW9߫\ĐV{(*K)Oy\NCl>G\LJ"/,~/D'Ոm5Q,%9XQ*H(Hch Q{`T1`fXIŽ0$z-0NJZěY 3!wC{ @_j/XX1 CLB9DP>#A.|B5Q;HNм9K4P@/1] IDAT C@04ZGfzhFA=҅2ά LK2C z0zl-""A揪Q?-Tzźbѻn^QE5YpJ[ۿDmqԙ-&sv yo0{)L]CNN= ,XRv;טW"J땎 j똊h tK?T.khQk`leUh{`.vR(Zi\Wh0 f}XDiC2HZ3ЪyoW+cI9_4; u 215{SƆ92~^ +UN8|oJ5Gs0,@!S1:DI]D}ID DŠ̴ⴴHbtJ]EBCcZ7nZC\hTA4'\!T0 i뉖|)o,EN'xǏ>|r++kI}]ZH}_S1at'(~ H]UG83q\mX&Q8ZBMliF,!Z yԕ'=Jqf<%P-&5N@U0wwdHwp ;thP8-?X[SXɩ/uHvCK QoToP \Lci!gXY.,O~^8sgŀ8PZgBv`}ȍڎP؉37F&{},eMכBwaf=$\zNu[;t譭[.ԅKls(H oj= !>d xFu8Sst9 XH}!LWq0r"$SЁb4$i.aQB¡Wx, jjЩ/7v. ۱$8G9(9mG5LXēTn7xrv "Z8f@cjǖ_}Of8vE1d(6nFyKA^`#vrv(RA tP`1yфp;&+>9xv1`S9)-7M<#L+y+#Txri뿏8@f9Gb1xzQg2H7a!T4(1VsZ_A 70UlѬa*[xF1>7#.g`.7 s:fĊ8\Ɍ-8.v "<;bepxYgr`10uesE̓d09 Y#f1ԥS +xP79cPQcZQX98CDwTM9:`] ގL: >nxAC\Lx,]σ(TfqAڸDw O.։>%0s$3 RezL4 Y,[l Ht9{2X,foaq L>G A@-33 z0a"͠"&p,[,&0:||EPbLjǠ(bY})g2γѲ1T,` Mz$f u<5O' l;e7PBܥuV|ϗXz@gkq }8EAyjOƱ|=nTa`Yn8&UnQQ>Ws039TP80 9}9P xq8r3U,ɄPl28AbL*XTzCUX@_  *q_9L<]*S.Q`s,|~҃j;5FW^b=|DUx5G 54-}1Z,tc5ʠ"AOl5gSy\8Pu\TÈ6~XyyasG5 V;?TzhK l|Sa.{T`0cjaYݨCQ0"0ۍl3R?΀}F{۠ϳt-௨1#lBBg N03ts<67#djaCzy@' uС8]pGBqn07pv3;džJ8Eg=p^7y.3*}-K8V\h!pܺzMDSvTd},=q0 D92xY7& 6- <]a|Gf|`n͛Lͪ|V L=Ys-sz]&x aT<^\?q̇@ x(0͛LzFr6I49پ95h.urphq\/JOW^c/m`BOekIYEF#2lhqLQAmӡ\>`,fv9ȍ 4gUhcP 9D >:gGl1 ⴢ(=: Fc+e4Q|`8{[/l}2jNnNVc".v^>nR 11.a^q\gSmXQZDg@eLHm MWXM "i1Ւχy_UR`28z W_E1;TA>XݡSoUEFAe۱v:AGll=t4<C'GOP[ J-0=L(f2FĆއ `dt٬I7˓frJ'pnn`76Hm1c8n% 8P3ky*ܾcusP`rLSC8j3fy[f9hjj}d6plL'8СCqxlQ&f[f@*Sf8; ʤ lvUMf]?sGqp#n&qԴ?}5Gf]Ѿ>p3 Z-xy /+lqv=h&4BGA@ =uK^߂Ͳ- =A~ t]^E͆p%r!VJ z &Tu\.g"WmНGG`]'1g -|XZ"ńg P;i bB>ّ3; {a?[9.*lIGN7OKEYal_5I~MH׏w@Ve l0UBC'bWӦlJ_MP 6~Κes6[~'G3߁9۸r3Ht;nwYwknmB>Z~!nu`mr>hs;:.$o2k03]x%v'b72*˹2ho#Λ D+㑁1i3f> \~Z\vSf~ Wԭ`?ZDNxo"0-9FIIw\ Pn.˥S'C~]RnHkՉI_'7r$Y|_SyոŲz<1~b4X!ee=F>1zrY,%*ˊ-'VjEZMlܮhZҵJJ,1WF.]VMCyso3cAFO>'?1OrQ߮q:N j cwA לqȃP8\\j/%ֱ.D;ϐуZCFq NTK.]q#w-!Ś*(IbI'+@uMj=]q 9mh=.d*f2,0) DTX%5.hRӥ%~i!a .DuuXN~ "qcmVK7E`(֊ǭJj/@.j-RL8ZuQ$.VF]K=P,=P7tV,Ҋ" GZHOFԸй+B"%vk%I*5Y;?y Pr;'VY;%-Wg4bVKQ֯s%󵵚J2ofv1\ah Ťw*̋yr^+fjÜg0'Ie5k"/dvՊ ZR*e2 yl̤%.k 0$3JRae2⮲I&Y⧺q!1YfR+c"LtI2VzQǡq3\k4I4hs!=UjՙL3.Vf%VVQI\1HU05cZk> ]lyqzgMNt}DPi8!0Kĝhp8ϿYGD_GT?]Y G!ǹY܏0;molg΢?(: 7oˢԎ)Y! BGߒW泟?)ԩGO;_C?G-eSH·ef@THFm3T[gǷb(! ։M H$G|+^ozpy ̿O|Q0y4pLo$^é3懓:&d$ttfg$' oiڒ53QQ15eKچgR;RnN&fSGnHHr&kHpa!@%k*#un:s_ 欇+-IjDrgLu$%v$6uʶ |32œۣA :l òP:4\P*4vv&tM u1=b+L1:2Eؒ +Mt=`r8L4cVŽabdD¾Uz4Ub$wttt&uDRRB' ixpm~YzOҽ}PԬ[BaprTSI[JK$ SJֱib8GTױgɅRe u&p[6H?N Cᦙm#=uu=.p/'Rv$luNd4tȒdpk+M. hz"y_gViDpB}#uY=۶fxExOf|l;痔`INMN.LIN%ؒl 3䋤&R Rd3I} DgTr V S3I'2s: ɝOOoy7l|w¹te4PBg("X鬩Q7:9 љpuVjKHnbfWy)ħ3~(moa=Px?>Gs :o͠|-I[K$ОTGTOiFgOFhr32Rm[öuf: 3l3uufF㖤Osti-agb0™i[G]VB'A=3Q.#)c"ilL*NK@TSSu ÎatS0Q8aX] n@j39FӶxO~۟Sy)57''LXHp,)i[l[JC2`^@H;*Jsb+ ƣDO=zwޟ==S~YOjOO6t: 73(#5RTԬ_eLJ':lT eӶn_<4pHHVRiVaV0ºJN΂%T30SY3#=YLLmYS京*6q8t805N4#ZO♬:ppSVag"oic8'#+ bHFViRVj)(ַyEn""J'o *6uKXo*(Z>-ir [b;ͤV疇Eku*2SW>Ԋgafֻk.d,hjG2-K(iDo6H觛ymEg9o \4-q_GF^{o.yoe}^]=Ŧޞ CyYHFJ+^nE|kFoA?^CCo5hE]e;Q>^CQoYCލ[ksb2OOxԛr4Gexo?fx4.Kxƥ7= r\ p7X"B^ä"HϘVMZۥru- g㱈,]EeR `Z4V&Wc\DSE.8b g`x4( Lv5HsH\'˪]bm#8Z0ÿ 0?\ܽeIvDIF;).brԊч$ E$bt)rEDaM{E"Lq1VH "adԊ,Z"%Z eLDZd|P֥1DLhܣa&63ӫ1jQ~q#S^kW22-! 8AW_ `P'_|e4 ŵ90p Q"rCX8:P%8{>ZD_["mרkX>07`47dM=%Z Qّ\iBl:)Za8IfT?N$Hs|̧gglUW_]?6`N#Q"\ v' H:x.:T8y Q& 4򂴫ւĢh3qRF־fFyA N\0%恡auMh~nDlF8eP\rg88BTqiDܰET:U~))#5OzQ ?B?SqIENDB`code-b3b483e0fd5e/doc/implementation.txt0000644000000000000000000000334007437047562016363 0ustar 00000000000000Implementation notes ==================== [see also the roundup package docstring] There have been some modifications to the spec. I've marked these in the source with 'XXX' comments when I remember to. In short: Class.find() - may match multiple properties, uses keyword args. Class.filter() - isn't in the spec and it's very useful to have at the Class level. CGI interface index view specifier layout part - lose the '+' from the sorting arguments (it's a reserved URL character ;). Just made no prefix mean ascending and '-' prefix descending. ItemClass - renamed to IssueClass to better match it only having one hypderdb class "issue". Allowing > 1 hyperdb class breaks the "superseder" multilink (since it can only link to one thing, and we'd want bugs to link to support and vice-versa). templates - the call="link()" is handled by special-case mechanisms in my top-level CGI handler. In a nutshell, the handler looks for a method on itself called 'index%s' or 'item%s' where %s is a class. Most items 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" (from an index) - the link text is the property specified. template - added functions that I found very useful: List, History and Submit. template - items must specify the message lists, history, etc. Having them by default was sometimes not wanted. template - index view determines its default columns from the template's tags. template - menu() and field() look awfully similar now .... ;) roundup.py - the command-line tool has a lot more commands at its disposal code-b3b483e0fd5e/doc/index.html0000644000000000000000000013453307437047562014603 0ustar 00000000000000 Roundup: an Issue-Tracking System for Knowledge Workers

Roundup (0.3.1)

An Issue-Tracking System for Knowledge Workers

Contents

Installation

Prerequisites

Python 2.1.1 is required for the correct operation of roundup.

Download the latest version from http://www.python.org/.

Getting Roundup

Download the latest version from http://roundup.sf.net/.

Installing Roundup

  1. Run:
    python setup.py install
  2. If you would prefer the scripts installed in somewhere other than /usr/local/bin, add "--install-scripts=<dir>" to the command:
    python setup.py install --install-scripts=<dir>
  3. The command:
    python setup.py install --help
    gives all the options available for installation.

Getting Started

The following instructions assume that you have installed roundup. If you haven't, you may still proceed - just preface all commands with "./" ie. "./roundup-admin init".

The Instance

We'll be referring to the term instance a lot from now on. An instance is a directory in your filesystem that is where all the information about a live issue tracker database is stored. The data that is entered as issues, the users who access the database and the definition of the database itself all reside there:
  1. Hyperdatabase
    This is the lowest component of Roundup and is where all the issues, users, file attachments and messages are stored.
  2. Database schema
    This describes the content of the hyperdatabase - what fields are stored for issues, what user information, etc. Being stored in the instance, 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.
  3. Web Interface
    The web interface templates are defined in the instance 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.
Instances are created using the roundup-admin tool.

Command Line Tool

To initiliase a new instance, run roundup-admin init. You will be asked a series of questions:
  1. Instance home directory
  2. Schema to use
  3. Database back-end to use
  4. Administration user "admin" password.
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 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 start.

Roundup is configurable using an instance_config.py file in the instance home. It should be edited before roundup is used, and may have the following variable declarations:

  1. MAILHOST
    The SMTP mail host that roundup will use to send mail
  2. MAIL_DOMAIN
    The domain name used for email addresses
  3. ISSUE_TRACKER_WEB
    The web address of the issue tracker's web interface

The email addresses used by the system by default are:

  1. ISSUE_TRACKER_EMAIL - issue_tracker@MAIL_DOMAIN
    submissions of issues
  2. ADMIN_EMAIL - roundup-admin@MAIL_DOMAIN
    roundup's internal use (problems, etc)

E-Mail Interface

Setup 1: As a mail alias pipe process

Set up a mail alias called "issue_tracker" as (include the quote marks):
"|/usr/bin/python /usr/local/bin/roundup-mailgw <instance_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>
To test the mail gateway on unix systems, try:
echo test |mail -s '[issue] test' issue_tracker@your.domain

Setup 2: As a regular cron job using a mailbox source

Set the roundup-mailgw up to run every 10 minutes or so. For example:
10 * * * * /usr/local/bin/roundup-mailgw <instance_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" will be "/var/mail/issue_tracker".

Setup 3: As a regular cron job using a POP source

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>
where pop_spec is "username:password@server" that specifies the roundup submission user's POP account name, password and server.

Web Interface

This software will work through apache or stand-alone.

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 ROUNDUP_INSTANCE_HOMES on the command-line using "name=home" pairs.
  2. roundup-server [hostname port] (hostname may be "")
  3. Load up the page /<instance name>/index where instance name is the name you nominated in ROUNDUP_INSTANCE_HOMES.
Apache:
  1. The CGI script is found in the cgi-bin directory of the roundup distribution.
  2. Make sure roundup.cgi is executable. Edit it at the top - ROUNDUP_INSTANCE_HOMES needs to know about your instance.
  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 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_DEBUG "0"
  7. On Windows, write a batch file "roundup.bat" similar to the one below and place it into your cgi-bin directory: 
            @echo off
        set ROUNDUP_LOG=c:\Python21\share\roundup\cgi.log
        set ROUNDUP_INSTANCE_HOMES=Default=c:\Python21\share\roundup\instances\Default;
        set ROUNDUP_DEBUG=0
        c:\Python21\python.exe c:\Python21\share\roundup\cgi-bin\roundup.cgi

Users

Users and permissions

By default, roundup automatically creates one user when the instance database is initialised (using roundup-admin init). The user is "admin" and the password is the one you supply at that time.

If users attempt to use roundup in any manner and are not identified to roundup, they will be using the database in a read-only mode. That is, if roundup doesn't know who they are, they can't change anything. This has the following repurcussions:

Command-line interface
The data modification commands (create, init, retire, set) are performed as the "admin" user. It is therefore important that the database be protected by the filesystem if protection is required. On a Unix system, the easiest and most flexible method of doing so is:
  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):
    mkdir instance_home
chown issue_tracker:issue_tracker instance_home
chmod g+rwxs instance_home
roundup-admin -i instance_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 gateways, then be sure to include those users in the group too (on some Linux systems, these users are "www" or "apache" and "mail".)
E-Mail interface
Users are identified by e-mail address - a new user entry will be created for any e-mail address that is not recognised, so users are always identified by roundup.
Web interface
Unidentified users have read-only access. If the users database has an entry with the username "anonymous", then unidentified users are automatically logged in as that user. This gives them write access.

*** anonymous access and the ANONYMOUS_* configuratins.

Adding users

To add users, use one of the following interfaces:
  1. On the web, access the URL .../<instance 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 address=richard@clown.org
    Supply the admin username and password. roundup-admin will print the id of the new user.
  3. Any e-mail sent to roundup from an address that doesn't match an existing user in the database will result in a new user entry being created for that user.

Issues

To add issues, use one of the following interfaces:
  1. On the web, access the URL .../<instance 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"
    Supply the admin username and password. roundup-admin will print the id of the new issue.
  3. Any e-mail sent to roundup with the subject line containing [issue] will automatically created a new issue in the database using the contents of the e-mail.

User Guide

Command Line Tool

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

Options:
-i instance home specify the issue tracker "home directory" to administer
-u the user[:password] to use for commands
-c when outputting lists of data, just comma-separate them

Command Help
commit Usage: commit

The changes made during an interactive session are not
automatically written to the database - they must be committed
using this command.

One-off commands on the command-line are automatically committed if
they are successful.
create Usage: create classname property=value ...

This creates a new entry of the given class using the property
name=value arguments provided on the command line after the "create"
command.
display Usage: display designator

This lists the properties and their associated values for the given
node.
export Usage: export class[,class] destination_dir

This action exports the current data from the database into
tab-separated-value files that are placed in the nominated destination
directory. The journals are not exported.
find Usage: find classname propname=value ...

Find the nodes 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.
get Usage: get property designator[,designator]*

Retrieves the property value of the nodes specified by the designators.
help Usage: help topic

commands  -- list commands
 -- help specific to a command
initopts  -- init command options
all       -- all available help
history Usage: history designator

Lists the journal entries for the node 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 added to
the existing database - if you want to create a new database using the
imported data, then create a new database (or, tediously, retire all
the old data.)
initialise Usage: initialise [template [backend [admin password]]]

The command will prompt for the instance home directory (if not supplied
through INSTANCE_HOME or the -i option. The template, backend and admin
password may be specified on the command-line as arguments, in that
order.

See also initopts help.
list Usage: list classname [property]

Lists all instances 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 retrieved by
the list or find commands, and its key value may be re-used.
rollback Usage: rollback

The changes made during an interactive session are not
automatically written to the database - they must be committed
manually. This command undoes all those changes, so a commit
immediately after would make no changes to the database.
set Usage: set designator[,designator]* propname=value ...

Sets the property to the value for all designators given.
specification Usage: specification classname

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 not
specified, all properties are displayed. By default, the column widths
are the width of the property names. The width may be explicitly defined
by defining the property as "name:width". For example::
  roundup> table priority id,name:10
  Id Name
  1  fatal-bug 
  2  bug       
  3  usability 
  4  feature

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 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".

A designator is a classname and a nodeid concatenated, eg. bug1, user10, ...

Property values are represented as strings in command arguments and in the printed results:

  • Strings are, well, strings.
  • Password values will display as their encoded value.
  • Date values are printed in the full date format in the local time zone, and accepted in the full format or any of the partial formats explained below.
    Input of...Means...
    "2000-04-17.03:45"2000-04-17.08:45:00
    "2000-04-17"2000-04-17.00:00:00
    "01-25"yyyy-01-25.00:00:00
    "08-13.22:13"yyyy-08-14.03:13:00
    "11-07.09:32:43"yyyy-11-07.14:32:43
    "14:25"yyyy-mm-dd.19:25:00
    "8:47:11"yyyy-mm-dd.13:47:11
    ".""right now"
  • Link values are printed as node designators. When given as an argument, node designators and key strings are both accepted.
  • Multilink values are printed as lists of node designators joined by commas. 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.
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 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.

Where the command changes data, a login name/password is required. The login may be specified as either "name" or "name:password".

  • ROUNDUP_LOGIN environment variable
  • the -u command-line option
If either the name or password is not supplied, they are obtained from the command-line.

Web Interface

Index views may be modified by the following arguments: 
    :sort    - sort by prop name, optionally preceeded with '-'
             to give descending or nothing for ascending sorting.
    :group   - group by prop name, optionally preceeded with '-' or
             to sort in descending or nothing for ascending order.
    :filter  - selects which props should be displayed in the filter
             section. Default is all.
    :columns - selects the columns that should be displayed.
             Default is all.
    propname - selects the values the node properties given by propname
             must have (very basic search/filter).
Not sure what to put in here...

E-Mail Gateway

Performing Actions

The subject line of the incoming message is examined to determine whether the message is an attempt to create a new item or to discuss an existing item. A designator enclosed in square brackets is sought as the first thing on the subject line (after skipping any "Fwd:" or "Re:" prefixes).

If an item designator (class name and id number) is found there, the newly created "msg" node is added to the "messages" property for that item, and any new "file" nodes are added to 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.

Setting Properties

The e-mail interface also provides a simple way to set properties on items. At the end of the subject line, propname=value pairs can be specified in square brackets, using the same conventions as for the roundup set shell command. explanatory message given in the exception.

Message content

Incoming messages are examined for multiple parts:
  • 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.
  • 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 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 non-quoting section becomes the summary of the message.

Address handling

All of the addresses in the To: and Cc: headers of the incoming message are looked up among the user nodes, 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 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 no passwords.

Triggers

Both cases may trigger detectors (in the first case we are calling the set() method to add the message to the item's spool; in the second case we are calling the create() method to create a new node). If an auditor raises an exception, the original message is bounced back to the sender with the

Nosy Lists

A standard detector is provided that watches for additions to the "messages" property. When a new message is added, the detector sends it to all the users on the "nosy" list for the item that are not already on the "recipients" list of the message. Those users are then appended to the "recipients" property on the message, so multiple copies of a message are never sent to the same user. The journal recorded by the hyperdatabase on the "recipients" property then provides a log of when the message was sent to whom.

Customising Roundup

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

Instance Configuration

The instance_config.py located in your instance home contains the basic configuration for the web and e-mail components of roundup's interfaces. This file is a Python module. The default instance_config.py is given below - as you can see, the MAIL_DOMAIN must be edited before any interaction with the instance is attempted. 

MAIL_DOMAIN=MAILHOST=HTTP_HOST=None
HTTP_PORT=0

# roundup home is this package's directory
INSTANCE_HOME=os.path.split(__file__)[0]

# The SMTP mail host that roundup will use to send mail
if not MAILHOST:
    MAILHOST = 'localhost'

# The domain name used for email addresses.
if not MAIL_DOMAIN:
    MAIL_DOMAIN = 'fill.me.in.'

# the next two are only used for the standalone HTTP server.
if not HTTP_HOST:
    HTTP_HOST = ''
if not HTTP_PORT:
    HTTP_PORT = 9080

# This is the directory that the database is going to be stored in
DATABASE = os.path.join(INSTANCE_HOME, 'db')

# This is the directory that the HTML templates reside in
TEMPLATES = os.path.join(INSTANCE_HOME, 'html')

# 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
ISSUE_TRACKER_WEB = 'http://some.useful.url/'

# The email address that roundup will complain to if it runs into trouble
ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN

# 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'

# Deny or allow anonymous users to register through the web interface
ANONYMOUS_REGISTER = 'deny'

# Send nosy messages to the author of the message
MESSAGES_TO_AUTHOR = 'no'       # either 'yes' or 'no'

Instance Schema

Note: if you modify the schema, you'll most likely need to web interface to reflect your changes.

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

    pri = Class(db, "priority", name=String(), order=String())
    pri.setkey("name")
    pri.create(name="critical", order="1")
    pri.create(name="urgent", order="2")
    pri.create(name="bug", order="3")
    pri.create(name="feature", order="4")
    pri.create(name="wish", order="5")

    stat = Class(db, "status", name=String(), order=String())
    stat.setkey("name")
    stat.create(name="unread", order="1")
    stat.create(name="deferred", order="2")
    stat.create(name="chatting", order="3")
    stat.create(name="need-eg", order="4")
    stat.create(name="in-progress", order="5")
    stat.create(name="testing", order="6")
    stat.create(name="done-cbb", order="7")
    stat.create(name="resolved", order="8")

    keyword = Class(db, "keyword", name=String())
    keyword.setkey("name")

    user = Class(db, "user", username=String(), password=String(),
        address=String(), realname=String(), phone=String(), organisation=String())
    user.setkey("username")
    user.create(username="admin", password=adminpw, address=instance_config.ADMIN_EMAIL)

    msg = FileClass(db, "msg", author=Link("user"), recipients=Multilink("user"), 
        date=Date(), summary=String(), files=Multilink("file"))

    file = FileClass(db, "file", name=String(), type=String())

    issue = IssueClass(db, "issue", assignedto=Link("user"),
        topic=Multilink("keyword"), priority=Link("priority"), status=Link("status"))
    issue.setkey('title')

Classes and Properties - creating a new information store

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

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

Class and Nodes

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.

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.

Properties

A Class is comprised of one or more properties of the following types:
  • String properties are for storing arbitrary-length strings.
  • Password properties are for storing encoded arbitrary-length strings. The default encoding is defined on the roundup.password.Password class.
  • Date properties store date-and-time stamps. Their values are Timestamp objects.
  • A Link property refers to a single other node 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. The value is a list of integers.

FileClass

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

IssueClass

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

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

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

The value of the "creation" property is the date when a node was created, and the value of the "activity" property is the date when any property on the node 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 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 of the key property. That is, we can refer to users by their username, e.g. let's say that there's an issue in roundup, issue 23. There's also a user, richard who happens to be user 2. To assign an issue to him, we could do either of:

roundup-admin set issue assignedto=2

or

roundup-admin set issue assignedto=richard

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

create(information)

Create a node in the database. This is generally used to create nodes in the "definitional" classes like "priority" and "status".

Web Interface

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 (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 the access through its main() method. This means that you can do pretty much anything you want as a web interface to your instance.

Most customisation of the web view can be done by modifying the templates in the instance html directory. These are divided into index, item and newitem views. The newitem view is optional - the item view will be used if the newitem view doesn't exist.

Repurcussions of changing the instance schema

If you choose to change the instance schema you will need to ensure the web interface knows about it:
  1. Index, item and filter pages for the relevant classes may need to have properties added or removed,
  2. The default page header relies on the existence of, and some values of the priority, status, assignedto and activity classes. If you change any of these (specifically if you remove any of the classes or their default values) you will need to implement your own pagehead() method in your instance's interfaces.py module.

Displaying Properties

Properties appear in the user interface in three contexts: in indices, in editors, and as filters. For each type of property, there are several display possibilities. For example, in an index view, a string property may just be printed as a plain string, but in an editor view, that property should be displayed in an editable field.

The display of a property is handled by functions in the htmltemplate module.

Displayer functions are triggered by <display> tags in templates. The call attribute of the tag provides a Python expression for calling the displayer function. The three standard arguments are inserted in front of the arguments given. For example, the occurrence of 

    <display call="plain('status')">
in a template triggers a call the "plain" function. The displayer functions can accept extra arguments to further specify details about the widgets that should be generated. By defining new displayer functions, the user interface can be highly customized.

The displayer functions are
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 ids if the linked class has no key property).

Options:
escape (boolean) - HTML-escape the resulting text.

field Display a property like the plain displayer above, but in a form field to be edited. Strings, Dates and Intervals use TEXT fields, Links use SELECT fields and Multilinks use SELECT MULTIPLE fields.

Options:
size (number) - width of TEXT fields.
height (number) - number of nows in SELECT MULTIPLE tags.
showid (boolean) - true includes the id of linked nodes in the SELECT MULTIPLE fields.

menu For a Links and Multilinks, display the same field as would be generated using field.
link For a Link or Multilink property, display the names of the linked nodes, hyperlinked to the item views on those nodes.

For other properties, link to this node with the property as the text.

Options:
property (property name) - the property to use in the second case.

count For a Multilink property, display a count of the number of links in the list.

Arguments:
property (property name) - the property to use.

reldate Display a Date property in terms of an interval relative to the current date (e.g. "+ 3w", "- 2d").

Arguments:
property (property name) - the property to use.

Options:
pretty (boolean) - display the relative date in an English form.

download For a Link or Multilink property, display the names of the linked nodes, hyperlinked to the item views on those nodes.

For other properties, link to this node with the property as the text.

In all cases, append the name (key property) of the item to the path so it is the name of the file being downloaded.

Arguments:
property (property name) - the property to use.

checklist For a Link or Multilink property, display checkboxes for the available choices to permit filtering.

Arguments:
property (property name) - the property to use.

note Display the special notes field, which is a text area for entering a note to go along with a change.
list List the nodes specified by property using the standard index for the class.

Arguments:
property (property name) - the property to use.

history List the history of the item.
submit Add a submit button for the item.

Index Views

An index view contains two sections: a filter section and an index section. The filter section provides some widgets for selecting which items appear in the index. The index section is a table of items.

Index View Specifiers

An index view specifier (URL fragment) looks like this (whitespace has been added for clarity): 

/issue?status=unread,in-progress,resolved&
        topic=security,ui&
        :group=+priority&
        :sort=-activity&
        :filters=status,topic&
        :columns=title,status,fixer

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 are displayed. The filter part consists of all the other query parameters, and it determines the criteria by which nodes 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.

The filter part selects the union of the sets of items with values matching any 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 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 by activity, arranged in descending order. The filter section shows filters for the "status" and "topic" properties, and the table includes columns for the "title", "status", and "fixer" properties.

Associated with each item class is a default layout specifier. The layout specifier in the above example is the default layout to be provided with the default bug-tracker schema described above in section 4.4.

Filter Section

The template for a filter section provides the filtering widgets at the top of the index view. Fragments enclosed in <property>...</property> tags are included or omitted depending on whether the view specifier requests a filter for a particular property.

A property must appear in the filter template for it to be available as a filter.

Here's a simple example of a filter template. 

<property name=status>
    <display call="checklist('status')">
</property>
<br>
<property name=priority>
    <display call="checklist('priority')">
</property>
<br>
<property name=fixer>
    <display call="menu('fixer')">
</property>

The standard index generation code appends a section to the index pages which allows selection of the filters - from those which are defined in the filter template.

Index Section

The template for an index section describes one row of the index table. Fragments enclosed in <property>...</property> tags are included or omitted depending on whether the view specifier requests a column for a particular property. The table cells should contain <display> tags to display the values of the item's properties.

Here's a simple example of an index template. 

<tr>
    <property name=title>
        <td><display call="plain('title', max=50)"></td>
    </property>
    <property name=status>
        <td><display call="plain('status')"></td>
    </property>
    <property name=fixer>
        <td><display call="plain('fixer')"></td>
    </property>
</tr>

Sorting

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 sorted according to how many links are present.

Item Views

An item view contains an editor section and a spool section. At the top of an item view, links to superseding and superseded items are always displayed.

Editor Section

The editor section is generated from a template containing <display> tags to insert the appropriate widgets for editing properties.

Here's an example of a basic editor template. 

<table>
<tr>
    <td colspan=2>
        <display call="field('title', size=60)">
    </td>
</tr>
<tr>
    <td>
        <display call="field('fixer', size=30)">
    </td>
    <td>
        <display call="menu('status')>
    </td>
</tr>
<tr>
    <td>
        <display call="field('nosy', size=30)">
    </td>
    <td>
        <display call="menu('priority')>
    </td>
</tr>
<tr>
    <td colspan=2>
        <display call="note()">
    </td>
</tr>
</table>

As shown in the example, the editor template can also request the display of a "note" field, which is a text area for entering a note to go along with a change.

When a change is submitted, the system automatically generates a message describing the changed properties.

If a note is given in the "note" field, the note is appended to the description. The message is then added to the item's message spool (thus triggering the standard detector to react by sending out this message to the nosy list).

The message also displays all of the property values on the item and indicates which ones have changed. An example of such a message might be this: 

Polly's taken a turn for the worse - this is now really important!
-----
title: Polly Parrot is dead
priority: critical
status: unread -> in-progress
fixer: terry
keywords: parrot,plumage,perch,nailed,dead

Spool Section

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 message takes you to its content.

The <property> tag used in the index may also be used here - it checks to see if the nominated Multilink property has any entries. This can be used to eliminate sections of the spool section if the property has no entries. 

<property name="files">
 <tr class="strong-header">
  <td><b>Files</b></td>
 </tr>

 <tr>            
  <td><display call="list('files')"></td>
 </tr>
</property>

Acknowledgements

Go Ping, you rock! Also, go Bizar Software for letting me implement this system on their time.

 

$Id: index.html,v 1.27 2002-01-23 05:10:27 richard Exp $

 

code-b3b483e0fd5e/doc/installation.stx0000644000000000000000000000167107437047562016043 0ustar 00000000000000*Roundup (0.4.1): An Issue-Tracking System for Knowledge Workers* `Table of contents`_ 1. Prerequisites_ 2. `Getting Roundup`_ 3. `Installing Roundup`_ Prerequisites ------------- Python 2.1.1 is required for the correct operation of roundup. Download the latest version from http://www.python.org/. Getting Roundup --------------- Download the latest version from http://roundup.sf.net/. Installing Roundup ------------------ Run: - "``python setup.py install``" - If you would prefer the scripts installed in somewhere other than "``/usr/local/bin``", add "``--install-scripts=``" to the command:: python setup.py install --install-scripts= - This command gives all the options available for installation:: python setup.py install --help Next: `Getting Started`_ .. _`table of contents`: index.html .. _`getting started`: getting_started.html $Id: installation.stx,v 1.1 2002-02-21 06:22:00 richard Exp $ code-b3b483e0fd5e/doc/overview.html0000644000000000000000000011451307437047562015336 0ustar 00000000000000 Roundup: an Issue-Tracking System for Knowledge Workers
[Software Carpentry logo]
[ACL Logo]
[CodeSourcery Logo]
Copyright (c) 2000 Ka-Ping Yee. This material may be distributed only subject to the terms and conditions set forth in the Software Carpentry Open Publication License, which is available at:
http://www.software-carpentry.com/openpub-license.html

Roundup

An Issue-Tracking System for Knowledge Workers

Ka-Ping Yee

lfw discorporated
ping@lfw.org

Contents

Overview

We propose an issue-tracking system called Roundup, which will manage a number of issues (with properties such as "description", "priority", and so on) and provide the ability to (a) submit new issues, (b) find and edit existing issues, and (c) discuss issues with other participants. The system will facilitate communication among the participants by managing discussions and notifying interested parties when issues are edited.

This design draws on experience from an existing implementation which we will refer to as "the Roundup prototype". The graphical interface we have in mind will resemble the main display of the prototype.

Background

A typical software project requires the management of many tasks, usually distributed among several collaborators. In fact, any project team could use a tool for sorting out and discussing all the relevant issues. A common approach is to set up some kind of "to-do" list that people can share.

However, to address the overall problem we need much more than just a shared to-do list; we need to manage a growing body of knowledge and experience to help a team collaborate effectively on a project. The issue-tracking tool becomes a nexus for communication: the Grand Central Station of the group intelligence.

The primary focus of this design is to help developers work together well, not to provide a customer service interface to the developers. This is not to say that the design is to be made unsuitable for customers to use. Rather, it is assumed that many of the same qualities that are good for supporting development (see below) are also good for non-developers using the system. Additional niceties for providing a safe or simplified interface to clients are intentionally deferred for later consideration.

A good issue-tracking system should have at least the following properties:

With a nod to the time-honoured computer science tradition of "filling in the fourth quadrant", we note that there are really four kinds of information flow going on here. The three mentioned qualities really address the first three quadrants of this 2-by-2 matrix, respectively:

  1. User push: a user submits information to the system.
  2. User pull: a user queries for information from the system.
  3. System push: the system sends information out to users.
  4. System pull: the system solicits information from users.
An example of the fourth kind of flow is voting. Voting isn't described in this design, but it should be noted as a potential enhancement.

  1. Low barrier to participation. The usefulness of the tool depends entirely on the information people contribute to it. It must be made as easy as possible to submit new issues and contribute information about existing issues.

  2. Straightforward navigation. It should be easy for users to extract information they need from the system to direct their decisions and tasks. They should be able to get a decent overview of things as well as finding specific information when they know what they're after.

  3. Controlled information flow. The users must have control over how much information and what information they get. A common flaw of some issue-tracking systems is that they inundate users with so much useless e-mail that people avoid the system altogether.


Guiding Principles

Simplicity. It is a strong requirement that the tool be accessible and understandable. It should be fairly obvious what different parts of the interface do, and the inner mechanisms should operate in ways that most users can easily predict.

Efficiency. We aim to optimize for minimum effort to do the most common operations, and best use of resources like screen real estate to maximize the amount of information that we summarize and present.

Generality. We try to avoid making unnecessary assumptions that would restrict the applicability of the tool. For example, there is no reason why one might not also want to use this tool to manage a design process, non-software projects, or organizational decisions.

Persistence. We prefer hiding or reclassifying information to deleting it. This helps support the collection of statistics later. If records are never destroyed, there is little danger in providing access to a larger community, and logging yields accountability, which may encourage better behaviour.

Okay, enough ranting. Let's get down to business.

Data Model

Roundup stores a number of items, each of which can have several properties and an associated discussion. The properties can be used to classify or search for items. The discussion is a sequence of e-mail messages. Each item is identified by a unique number, and has an activity log which records the time and content of edits made on its properties. The log stays fairly small since the design intentionally provides only small data types as item properties, and encourages anything large to be attached to e-mail where it becomes part of the discussion. The next section explains how items are organized.

The Hyperdatabase

In my opinion, forcing items into fixed categories is one of the most serious problems with the Roundup prototype. The hyperdatabase is an experimental attempt to address the problem of information organization, whose scope goes beyond just Roundup.
Often when classifying information we are asked to select exactly one of a number of categories or to fit it into a rigid hierarchy. Yet things only sometimes fall into one category; often, a piece of information may be related to several concepts. For example, forcing each item into a single topic category is not just suboptimal but counterproductive: seekers of that item may expect to find it in a different category and conclude that the item is not present in the database -- which has them worse off than if the items were not categorized at all.

Some systems try to alleviate this problem by allowing nodes to appear at multiple locations in a tree, as with "aliases" or "symbolic links" in a filesystem, for example. This does help somewhat, but we want to be even more flexible by allowing the organization of nodes into sets that may freely intersect. Rather than putting each node at exactly one place in an overall "grand scheme", a node can belong to as many sets as are appropriate. If we choose to represent the sets themselves as nodes and set membership as a link between nodes, we're now ready to present the definition of a hyperdatabase.

Perhaps it's too pretentious a name? You could say this is just like an object database. The hyperdatabase is hardly much of an invention; the intent is merely to emphasize querying on links rather than properties. (I haven't heard of this being done with object databases before, but plead ignorance if there's already a good name for this idea.)
A hyperdatabase is a collection of nodes that may be hyperlinked to each other (hence the name "hyperdatabase"). Each node carries a collection of key-value pairs, where some of the values may be links to other nodes. Any node may have an arbitrary number of outgoing and incoming links. Hyperdatabases are able to efficiently answer queries such as "what nodes link to this node?" and "what nodes does this node link to?"

Rationale

There are several reasons for building our own kind of database for Roundup rather than using an existing one. Requiring the installation of a full-blown third-party SQL database system would probably deter many potential users from attempting to set up Roundup; yet a real relational database would be too complicated to implement on our own. On the other hand, a hyperdatabase can be implemented fairly easily using one of the Python DBM modules, so we can take the "batteries-included" approach and provide it as part of the system. It's easier to build and understand than a true relational database (in accordance with our guiding principle of simplicity), but provides most of the query functionality we want.

A hyperdatabase is well suited for finding the intersection of a number of sets in which items belong. We expect that most of the queries people want to do will be of this form, rather than complicated SQL queries. For example, a typical request might be "show me all critical items related to security". The ability to store arbitrary key-value pairs and links on nodes gives it more flexibility than an RDBMS. Users are not going to be making thousands of queries per second, so it makes sense to optimize for simplicity and flexibility rather than performance.

Roundup's Hyperdatabase

For our application, we store each item as a node in a hyperdatabase. The item's properties are stored as key-value pairs on its node. Four types of properties are allowed: string, date, choice, and reference.

The string type is for short, free-form strings. String properties are not intended to contain large amounts of text, and it is recommended that they be presented as one-line fields to encourage brevity.

The date type is for calendar dates and times.

The choice type denotes a single selection from a number of options. A choice property entails a link from the node possessing the property to the node representing the chosen option.

The reference type is for a list of links to any number of other nodes in the in the database. A reference property, for example, can be used to refer to related items or topic categories relevant to an item.

For Roundup, all items have five properties that are not customizable:

  • a string property named description
  • a reference property named superseder
  • a reference property named nosy
  • a date property named creation
  • a date property named activity

The description property is a short one-line description of the item. The detailed description can go in the first e-mail message of the item's discussion spool.

The superseder property is used to support the splitting, joining, or replacing of items. When several items need to be joined into a single item, all the old items link to the new item in their superseder property. When an item needs to be split apart, the item references all the new items in its superseder propety. We can easily list all active items just by checking for an empty superseder property, and trace the path of an item's origins by querying the hyperdatabase for links.

The nosy property contains a list of the people who are interested in an item. This mechanism is explained in the section on Nosy Lists.

The creation property records the item's creation time. The activity property records the last time that the item was edited or a mail message was added to its discussion spool. These two properties are managed by Roundup and are not available to be edited like other properties.

Users of the system are also represented by nodes in the hyperdatabase, containing properties like the user's e-mail address, login name, and password.

The Default Schema

Roundup could be distributed with a few suggested schemas for different purposes. One possible enhancement to the software-development schema is a reference property named implements for connecting development items to design requirements which they satisfy, which should be enough to provide basic support for traceability. Clearly there is also potential for adding properties for related source files, check-ins, test results, regression tests for resolved items, and so on, though these have not yet been sufficiently well thought out to specify here.

It is hoped that the hyperdatabase together with the specializations mentioned above for Roundup will be applicable in a variety of situations (in accordance with our guiding principle of generality).

To address the problem at hand, we need a specific schema for items applied particularly to software development. Again, we are trying to keep the schema simple: too many options make it tougher for someone to make a good choice. The schema is written here in the same form that it would appear in a configuration file. 

    fixer = Reference()             # people who will fix the problem

    topic = Reference()             # relevant topic keywords

    priority = Choice("critical",   # panic: work is stopped!
                      "urgent",     # important, but not deadly
                      "bug",        # lost work or incorrect results
                      "feature",    # want missing functionality
                      "wish")       # avoidable bugs, missing conveniences

    status = Choice("unread",       # submitted but no action yet
                    "deferred",     # intentionally set aside
                    "chatting",     # under review or seeking clarification
                    "need-eg",      # need a reproducible example of a bug
                    "in-progress",  # understood; development in progress
                    "testing",      # we think it's done; others, please test
                    "done-cbb",     # okay for now, but could be better
                    "resolved")     # fix has been released

The fixer property assigns responsibility for an item to a person or a list of people. The topic property places the item in an arbitrary number of relevant topic sets (see the section on Browsing and Searching).

As previously mentioned, each item gets an activity log. Whenever a property on an item is changed, the log records the time of the change, the user making the change, and the old and new values of the property. This permits the later gathering of statistics (for example, the average time from submission to resolution).

We do not specify or enforce a state transition graph, since making the system rigid in that fashion is probably more trouble than it's worth. Experience has shown that there are probably two convenient automatic state transitions:

  • from unread to chatting when e-mail is written about an item
  • from testing to resolved when a new release of the software is made
Beyond these, in accordance with our principle of generality, we allow access to the hyperdatabase API so that scripts can automate transitions themselves or be triggered by changes in the database.

User Interface

Roundup provides its services through two main interfaces: e-mail and the Web. This division is chosen to optimize the most common tasks.

E-mail is best suited for the submission of new items since most people are most comfortable with composing long messages in their own favourite e-mail client. E-mail also permits them to mention URLs or attach files relevant to their submission. Indeed, in many cases people are already used to making requests by sending e-mail to a mailing list of people; they can do exactly the same thing to use Roundup without even thinking about it. Similarly, people are already familiar with holding discussions in e-mail, and plenty of valuable usage conventions and software tools already exist for that medium.

The Web, on the other hand, is best suited for summarizing and seeking information, because it can present an interactive overview of items. Since the Web has forms, it's also the best place to edit items.

Submission and Discussion

Nosy lists have actually been tried in practice, and their emergent properties have turned out to be very effective. They are one of the key strengths of the Roundup prototype, and often cause me to wonder if all mailing lists ought to work this way. Roundup could even replace Hypermail.

The system needs an address for receiving mail and an address that forwards mail to all participants. Each item has its own list of interested parties, known as its nosy list. Here's how nosy lists work:

  1. New items are always submitted by sending an e-mail message to Roundup. The "Subject:" field becomes the description of the new item. The message is saved in the mail spool of the new item, and copied to the list of all participants so everyone knows that a new item has been added. The new item's nosy list initially contains the submitter.
  2. All e-mail messages sent by Roundup have their "Reply-To:" field set to Roundup's address, and have the item's number in the "Subject:" field. Thus, any replies to the initial announcement and subsequent threads are all received by Roundup. Roundup notes the item number in the "Subject:" field of each incoming message and appends the message to the appropriate spool.
  3. Any incoming e-mail tagged with an item number is copied to all the people on the item's nosy list, and any users found in the "From:", "To:", or "Cc:" fields are automatically added to the nosy list. Whenever a user edits an item's properties in the Web interface, they are also added to the nosy list.

The effect is like each item having its own little mailing list, except that no one ever has to worry about subscribing to anything. Indicating interest in an issue is sufficient, and if you want to bring someone new into the conversation, all you need to do is Cc: a message to them. It turns out that no one ever has to worry about unsubscribing, either: the nosy lists are so specific in scope that the conversation tends to die down by itself when the issue is resolved or people no longer find it sufficiently important.

Each nosy list is like an asynchronous chat room, lasting only a short time (typically five or ten messages) and involving a small group of people. However, that group is the right group of people: only those who express interest in an item in some way ever end up on the list, so no one gets spammed with mail they don't care about, and no one who wants to see mail about a particular item needs to be left out, for they can easily join in, and just as easily look at the mail spool on an item to catch up on any messages they might have missed.

We can take this a step further and permit users to monitor particular topics or classifications of items by allowing other kinds of nodes to also have their own nosy lists. For example, a manager could be on the nosy list of the priority value node for "critical", or a developer could be on the nosy list of the topic value node for "security". The recipients are then determined by the union of the nosy lists on the item and all the nodes it links to.

Using many small, specific mailing lists results in much more effective communication than one big list. Taking away the effort of subscribing and unsubscribing gives these lists the "feel" of being cheap and disposable. The transparent capture of the mail spool attached to each issue also yields a nice knowledge repository over time.

Editing

Since Roundup is intended to support arbitrary user-defined schema for item properties, the editing interface must be automatically generated from the schema. The configuration for Roundup will include a template describing how to lay out the properties to present a UI for inspecting and editing items. For example: 

    <table width="100%">
    <tr><td align=right>Description:</td>
        <td><?property description size=70></td></tr>
    <tr><td align=right>Status:</td>
        <td><?property status></td></tr>
    </table>

To display the editing form for an item, Roundup substitutes an HTML form widget for each <?property ...> tag, and transfers attributes (such as size=70 in the above example) from the processing tag to the form widget's tag. Each type has its own appropriate editing widget:

  • string properties appear as text fields
  • date properties appear as text fields
  • choice properties appear as selection lists
  • reference properties appear as multiple-selection lists with a text field for adding a new option

We foresee the use of custom date fields for things like deadlines, so input fields for date properties should support some simple way of specifying relative dates (such as "three weeks from now").

The superseder property is a special case: although it is more efficient to store a superseder property in the superseded item, it makes more sense to provide a "supersedes" edit field on the superseding item. So we need a special widget on items for this purpose (perhaps something as simple as a text field containing a comma-separated list of item numbers will do). Links in the superseder property should appear on both the superseding and superseded items to facilitate navigating an item's pedigree.

After the editing widgets, the item inspection page shows a "note" text box and then a display of the messages in the discussion spool, like the Roundup prototype. This field lets you enter a note explaining your change when you edit the item, and the note is included in the notification message that goes out to tell the interested parties on the nosy list of your edits.

Browsing and Searching

The ideal we would like to achieve is to make searching as much like browsing as possible: the user simply clicks about on things that seem interesting, and the information narrows down comfortably until the goal is in sight. This is preferable to trying to digest a screen filled with widgets and buttons or entering a search expression in some arcane algebraic syntax.

Though the generation of each page amounts to a database query, so that the underlying mechanism is still a series of queries and responses, the user interface never separates the query from the response, so the experience is one of stepwise refinement.
While a one-shot search may be appropriate when you're looking for a single item and you know exactly what you want, it's not very helpful when you want an overview of things ("Gee, there are a lot more high-priority items than there were last week!") or trying to do comparisons ("I have some time today, so who is busiest and could most use some help?")

The browsing interface presents filtering functionality for each of the properties in the schema. As with editing, the interface is generated from a template describing how to lay out the properties. Each type of property has its own appropriate filtering widget:

  • string properties appear as text fields supporting case-insensitive substring match
  • date properties appear as a text field with an option to choose dates after or before the specified date
  • choice properties appear as a group of selectable options (the filter selects the union of the sets of items associated with the active options)
  • reference properties appear as a group of selectable options (the filter selects the intersection of the sets of items associated with the active options)

For a reference property like topic, one possibility is to show, as hyperlinks, the keywords whose sets have non-empty intersections with the currently displayed set of items. Sorting the keywords by popularity seems reasonable. Clicking on a keyword then narrows both the list of items and the list of keywords. This gives some of the feel of walking around a directory tree -- but without the restriction of having to select keywords in a particular hierarchical order, and without the need to travel all the way to the leaves of the tree before any items are visible.

Below the filtering form is a listing of items, with their properties displayed in a table. Rows in the table can also be generated from a template, as with the editing interface. This listing is the central overview of the system, and it should aim to maximize the density of useful information in accordance with our guiding principle of efficiency. For example, Bugzilla initially displays seven or eight items of the index, but only after the user has waded through three bewildering screens of form widgets. Jitterbug can't even fit any items at all in the first screenful, as it's taken up by artwork and adminstrative debris. In contrast, in the Roundup prototype, 25 high-priority issues are immediately visible, with most of the screen space devoted to their descriptions. Colour indicates the status of each item to help the eye sift through the index quickly.

In both Jitterbug and Bugzilla, items are sorted by default by ID, a meaningless field. Sorting by ID puts the issues in order by ascending submission date, which banishes recent issues far away at the bottom of the list. The Roundup prototype sorts items in sections by priority, and then within sections by the date of last activity. This reveals at a glance where discussion is most active, and provides an easy way for anyone to move an issue up in the list.

The page produced by a given set of browsing options constitutes a view. The options should all be part of the query parameters in the URL so that views may be bookmarked. A view specifies:

  • search strings for string properties
  • date ranges for date properties
  • acceptable values for choice properties
  • required values for reference properties
  • one or more sort keys
  • a list of properties for which to display filtering widgets

On each sort key there is the option to use sections -- that is, instead of making the property's value a column of the table, each possible value for the property is displayed at the top of a section and all the items having that value for that property are grouped underneath. This avoids wasting screen space with redundant information.

We propose that our default view should be:

  • all options on for priority and fixer
  • all options on except "resolved" for status
  • no options on for topic
  • primary sort by priority in sections
  • secondary sort by decreasing activity date

The starting URL for Roundup should immediately present the listing of items generated by this default view, with no preceding query screen.

Development Plan

The hyperdatabase is clearly a separable component which can be developed and tested independently to an API specification.

As soon as the API to the hyperdatabase is nailed down, the implementation of the Roundup database layer on top of the hyperdatabase can begin. (This refers to the data types and five fixed properties specific to Roundup.) This layer can also be tested separately.

When the interface to the Roundup hyperdatabase is ready, development can begin on the user interface. The mail handler and the Web interface can be developed in parallel and mostly independently of each other.

The mail handler can be set up for testing fairly easily: mail messages on its standard input can be synthesized; its output is outgoing mail, which can be captured by replacing the implementation of the "send mail" function; and its side effects appear in the hyperdatabase, which has a Python API.

The Web interface is not easily testable in its entirety, though the most important components of it can be unit tested, such as the component that translates a view specification into a list of items for display, and the component that performs replacements on templates to produce an editing or filtering interface.

Open Issues

The description of the hyperdatabase above avoids some issues regarding node typing that need to be better specified. It is conceivable that eventually Roundup could support multiple kinds of items with their own schemas.

To permit integration with external tools, it is probably a good idea to provide a command-line tool that exposes the hyperdatabase API. This tool will be left for a later phase of development and so isn't specified in detail here.

Generating the user interface from a template is like applying an XSL stylesheet to XML, and if there's a standard Python module for performing these transformations, we could use XML instead.

More thinking is needed to determine the best filtering interface for reference properties. The proposed interface works well for topic keywords, but it isn't clear what to do when there are too many keywords to display them all.

There has been a variety of reactions to the hyperdatabase from reviewers: some like it, some are neutral, and some would prefer a "standard" RDBMS solution. For those in the latter camp, note that it's still possible to build the Roundup database layer around an RDBMS if we really need to. The rest of the design, in particular the "nosy list" mechanism, remains intact.

The possibility of malice by registered users has been disregarded. The system is intended to be used by a co-operative group.

This design tries to address as many as possible of the suggested requirements mentioned on the contest page:

  • configuring states: Edit the schema.
  • setting state transition rules: We don't enforce any rules.
  • assigning responsibility: Set the fixer property.
  • splitting and joining: Use the superseder property.
  • hiding information: Add a property and a pre-defined view that filters on it.
  • secure protocols: Naturally HTTPS would be nice, though it's largely a webserver configuration issue; secure e-mail is not addressed.
  • archiving old issues: Tag them with a property.
  • identifying repeated issues: Use the superseder property.
  • connecting state changes to external operations: We provide an API to the database and the notification mechanism so it can be scripted.
  • non-Latin alphabets: Unicode in Python 1.6 will handle this for string properties, and we can leverage existing standards for internationalizing e-mail messages.
  • images and other binaries: Attach them to e-mail messages.
  • inspecting item state: Use the editing interface.
  • translation between system-dependent formats: This is not addressed.
  • performing searches: Use the browsing and filtering interface.
  • collecting statistics: Information is gathered in the activity log, though tools to summarize it are not described here.

Summary

Roundup is an issue-tracking system that also functions as a communications center and a knowledge repository. It combines the strengths of e-mail and the Web to try to provide the best possible user interaction.

  • The submission and discussion of items by e-mail, permitting participants to use an easy and familiar tool, achieves our goal of low barrier to participation.
  • The generic link-based structuring of data and use of incremental filtering rather than one-shot querying makes for straightforward navigation.
  • The use of nosy lists (a powerful replacement for e-mail discussion lists) to manage communication on a fine-grained level provides controlled information flow.

The use of a "hyperdatabase" as the core model for the knowledge repository gives us the flexibility to extend Roundup and apply it to a variety of domains by providing new item schemas and user-interface templates.

Roundup is self-contained and easy to set up, requiring only a webserver and a mailbox. No one needs to be root to configure the webserver or to install database software.

This design is based on an existing deployed prototype which has proven its strengths and revealed its weaknesses in heavy day-to-day use by a real development team.

Acknowledgements

My thanks are due to Christina Heyl, Jesse Vincent, Mark Miller, Christopher Simons, Jeff Dunmall, Wayne Gramlich, and Dean Tribble for reviewing this paper and contributing their suggestions.

   [Home]       [FAQ]       [License]       [Rules]       [Resources]       [Archives]   

Last modified 2001/04/06 11:50:59.9063 US/Mountain
code-b3b483e0fd5e/doc/spec.html0000644000000000000000000016252507437047562014430 0ustar 00000000000000 Software Carpentry Track: Roundup
[Software Carpentry logo]
[ACL Logo]
[CodeSourcery Logo]

Roundup

An Issue-Tracking System for Knowledge Workers

Ka-Ping Yee
ping@lfw.org

Implementation Guide

Contents

  1. Introduction
  2. The Layer Cake
  3. Hyperdatabase
    1. Dates and Date Arithmetic
    2. Nodes and Classes
    3. Identifiers and Designators
    4. Property Names and Types
    5. Interface Specification
    6. Application Example
  4. Roundup Database
    1. Reserved Classes
      1. Users
      2. Messages
      3. Files
    2. Item Classes
    3. Interface Specification
    4. Default Schema
  5. Detector Interface
    1. Interface Specification
    2. Detector Example
  6. Command Interface
    1. Interface Specification
    2. Usage Example
  7. E-mail User Interface
    1. Message Processing
    2. Nosy Lists
    3. Setting Properties
    4. Workflow Example
  8. Web User Interface
    1. Views and View Specifiers
    2. Displaying Properties
    3. Index Views
      1. Index View Specifiers
      2. Filter Section
      3. Index Section
      4. Sorting
    4. Item Views
      1. Item View Specifiers
      2. Editor Section
      3. Spool Section
  9. Deployment Scenarios
  10. Acknowledgements

1. Introduction

This document presents a description of the components of the Roundup system and specifies their interfaces and behaviour in sufficient detail to guide an implementation. For the philosophy and rationale behind the Roundup design, see the first-round Software Carpentry submission for Roundup. This document fleshes out that design as well as specifying interfaces so that the components can be developed separately.

2. The Layer Cake

Lots of software design documents come with a picture of a cake. Everybody seems to like them. I also like cakes (i think they are tasty). So i, too, shall include a picture of a cake here.

E-mail Client

Web Browser

Detector Scripts

Shell

E-mail User Interface

Web User Interface

Detector Interface

Command Interface

Roundup Database Layer

Hyperdatabase Layer

Storage Layer

The colourful parts of the cake are part of our system; the faint grey parts of the cake are external components.

I will now proceed to forgo all table manners and eat from the bottom of the cake to the top. You may want to stand back a bit so you don't get covered in crumbs.

3. Hyperdatabase

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.

The hyperdatabase is implemented on top of the storage layer, an external module for storing its data. The storage layer could be a third-party RDBMS; for a "batteries-included" distribution, implementing the hyperdatabase on the standard bsddb module is suggested.

3.1. Dates and Date Arithmetic

Before we get into the hyperdatabase itself, we need a way of handling dates. The hyperdatabase module provides Timestamp objects for representing date-and-time stamps and Interval objects for representing date-and-time intervals.

As strings, date-and-time stamps are specified with the date in international standard format (yyyy-mm-dd) joined to the time (hh:mm:ss) by a period ("."). Dates in this form can be easily compared and are fairly readable when printed. An example of a valid stamp is "2000-06-24.13:03:59". We'll call this the "full date format". When Timestamp objects are printed as strings, they appear in the full date format with the time always given in GMT. The full date format is always exactly 19 characters long.

For user input, some partial forms are also permitted: the whole time or just the seconds may be omitted; and the whole date may be omitted or just the year may be omitted. If the time is given, the time is interpreted in the user's local time zone. The Date constructor takes care of these conversions. In the following examples, suppose that yyyy is the current year, mm is the current month, and dd is the current day of the month; and suppose that the user is on Eastern Standard Time.

  • "2000-04-17" means <Date 2000-04-17.00:00:00>
  • "01-25" means <Date yyyy-01-25.00:00:00>
  • "2000-04-17.03:45" means <Date 2000-04-17.08:45:00>
  • "08-13.22:13" means <Date yyyy-08-14.03:13:00>
  • "11-07.09:32:43" means <Date yyyy-11-07.14:32:43>
  • "14:25" means <Date yyyy-mm-dd.19:25:00>
  • "8:47:11" means <Date yyyy-mm-dd.13:47:11>
  • the special date "." means "right now"

Date intervals are specified using the suffixes "y", "m", and "d". The suffix "w" (for "week") means 7 days. Time intervals are specified in hh:mm:ss format (the seconds may be omitted, but the hours and minutes may not).

  • "3y" means three years
  • "2y 1m" means two years and one month
  • "1m 25d" means one month and 25 days
  • "2w 3d" means two weeks and three days
  • "1d 2:50" means one day, two hours, and 50 minutes
  • "14:00" means 14 hours
  • "0:04:33" means four minutes and 33 seconds

The Date class should understand simple date expressions of the form stamp + interval and stamp - interval. When adding or subtracting intervals involving months or years, the components are handled separately. For example, when evaluating "2000-06-25 + 1m 10d", we first add one month to get 2000-07-25, then add 10 days to get 2000-08-04 (rather than trying to decide whether 1m 10d means 38 or 40 or 41 days).

Here is an outline of the Date and Interval classes. 

class Date:
    def __init__(self, spec, offset):
        """Construct a date given a specification and a time zone offset.

        'spec' is a full date or a partial form, with an optional
        added or subtracted interval.  'offset' is the local time
        zone offset from GMT in hours.
        """

    def __add__(self, interval):
        """Add an interval to this date to produce another date."""

    def __sub__(self, interval):
        """Subtract an interval from this date to produce another date."""

    def __cmp__(self, other):
        """Compare this date to another date."""

    def __str__(self):
        """Return this date as a string in the yyyy-mm-dd.hh:mm:ss format."""

    def local(self, offset):
        """Return this date as yyyy-mm-dd.hh:mm:ss in a local time zone."""

class Interval:
    def __init__(self, spec):
        """Construct an interval given a specification."""

    def __cmp__(self, other):
        """Compare this interval to another interval."""
        
    def __str__(self):
        """Return this interval as a string."""

Here are some examples of how these classes would behave in practice. For the following examples, assume that we are on Eastern Standard Time and the current local time is 19:34:02 on 25 June 2000. 

>>> Date(".")
<Date 2000-06-26.00:34:02>
>>> _.local(-5)
"2000-06-25.19:34:02"
>>> Date(". + 2d")
<Date 2000-06-28.00:34:02>
>>> Date("1997-04-17", -5)
<Date 1997-04-17.00:00:00>
>>> Date("01-25", -5)
<Date 2000-01-25.00:00:00>
>>> Date("08-13.22:13", -5)
<Date 2000-08-14.03:13:00>
>>> Date("14:25", -5)
<Date 2000-06-25.19:25:00>
>>> Interval("  3w  1  d  2:00")
<Interval 22d 2:00>
>>> Date(". + 2d") - Interval("3w")
<Date 2000-06-07.00:34:02>

3.2. Nodes and Classes

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 and types of its properties. The database permits the creation and modification of classes as well as nodes.

3.3. Identifiers and Designators

Each node has a numeric identifier which is unique among nodes in its class. The nodes 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 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 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 hyperlink.

3.4. Property Names and Types

Property names must begin with a letter.

A property may be one of five basic types:

  • String properties are for storing arbitrary-length strings.
  • 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 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. The value is a list of integers.

None is also a permitted value for any of these property types. An attempt to store None into a String property stores the empty string; an attempt to store None into a Multilink property stores an empty list.

3.5. Interface Specification

The hyperdb module provides property objects to designate the different kinds of properties. These objects are used when specifying what properties belong in classes. 

class String:
    def __init__(self):
        """An object designating a String property."""

class Date:
    def __init__(self):
        """An object designating a Date property."""

class Link:
    def __init__(self, classname):
        """An object designating a Link property that links to
        nodes in a specified class."""

class Multilink:
    def __init__(self, classname):
        """An object designating a Multilink property that links
        to nodes in a specified class."""

Here is the interface provided by the hyperdatabase. 

class Database:
    """A database for storing records containing flexible data types."""

    def __init__(self, storagelocator, journaltag):
        """Open a hyperdatabase given a specifier to some storage.

        The meaning of 'storagelocator' depends on the particular
        implementation of the hyperdatabase.  It could be a file name,
        a directory path, a socket descriptor for a connection to a
        database over the network, etc.

        The 'journaltag' is a token that will be attached to the journal
        entries for any edits done on the database.  If 'journaltag' is
        None, the database is opened in read-only mode: the Class.create(),
        Class.set(), and Class.retire() methods are disabled.
        """

    def __getattr__(self, classname):
        """A convenient way of calling self.getclass(classname)."""

    def getclasses(self):
        """Return a list of the names of all existing classes."""

    def getclass(self, classname):
        """Get the Class object representing a particular class.

        If 'classname' is not a valid class name, a KeyError is raised.
        """

class Class:
    """The handle to a particular class of nodes in a hyperdatabase."""

    def __init__(self, db, classname, **properties):
        """Create a new class with a given name and property specification.

        'classname' must not collide with the name of an existing class,
        or a ValueError is raised.  The keyword arguments in 'properties'
        must map names to property objects, or a TypeError is raised.
        """

    # Editing nodes:

    def create(self, **propvalues):
        """Create a new node 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
        corresponding properties or a TypeError is raised.  If this class
        has a key property, it must be present and its value must not
        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.
        """

    def get(self, nodeid, propname):
        """Get the value of a property on an existing node of this class.

        'nodeid' must be the id of an existing node 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.
        
        'nodeid' must be the id of an existing node 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.
        """

    def retire(self, nodeid):
        """Retire a node.
        
        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
        reuse the values of their key properties.
        """

    def history(self, nodeid):
        """Retrieve the journal of edits on a particular node.

        'nodeid' must be the id of an existing node of this class or an
        IndexError is raised.

        The returned list contains tuples of the form

            (date, tag, action, params)

        'date' is a Timestamp object specifying the time of the change and
        'tag' is the journaltag specified when the database was opened.
        'action' may be:

            'create' or 'set' -- 'params' is a dictionary of property values
            'link' or 'unlink' -- 'params' is (classname, nodeid, propname)
            'retire' -- 'params' is None
        """

    # Locating nodes:

    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.
        """

    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.

        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;
        otherwise a KeyError is raised.
        """

    def find(self, propname, nodeid):
        """Get the ids of nodes in this class which link to a given node.
        
        '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,
        or an IndexError is raised.
        """

    def list(self):
        """Return a list of the ids of the active nodes in this class."""

    def count(self):
        """Get the number of nodes 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.
        """

    # Manipulating properties:

    def getprops(self):
        """Return a dictionary mapping property names to property objects."""

    def addprop(self, **properties):
        """Add properties to this class.

        The keyword arguments in 'properties' must map names to property
        objects, or a TypeError is raised.  None of the keys in 'properties'
        may collide with the names of existing properties, or a ValueError
        is raised before any properties have been added.
        """

3.6. Application Example

Here is an example of how the hyperdatabase module would work in practice. 

>>> import hyperdb
>>> db = hyperdb.Database("foo.db", "ping")
>>> db
<hyperdb.Database "foo.db" opened by "ping">
>>> hyperdb.Class(db, "status", name=hyperdb.String())
<hyperdb.Class "status">
>>> _.setkey("name")
>>> db.status.create(name="unread")
1
>>> db.status.create(name="in-progress")
2
>>> db.status.create(name="testing")
3
>>> db.status.create(name="resolved")
4
>>> db.status.count()
4
>>> db.status.list()
[1, 2, 3, 4]
>>> db.status.lookup("in-progress")
2
>>> db.status.retire(3)
>>> db.status.list()
[1, 2, 4]
>>> hyperdb.Class(db, "issue", title=hyperdb.String(), status=hyperdb.Link("status"))
<hyperdb.Class "issue">
>>> db.issue.create(title="spam", status=1)
1
>>> db.issue.create(title="eggs", status=2)
2
>>> db.issue.create(title="ham", status=4)
3
>>> db.issue.create(title="arguments", status=2)
4
>>> db.issue.create(title="abuse", status=1)
5
>>> hyperdb.Class(db, "user", username=hyperdb.Key(), password=hyperdb.String())
<hyperdb.Class "user">
>>> db.issue.addprop(fixer=hyperdb.Link("user"))
>>> db.issue.getprops()
{"title": <hyperdb.String>, "status": <hyperdb.Link to "status">,
 "user": <hyperdb.Link to "user">}
>>> db.issue.set(5, status=2)
>>> db.issue.get(5, "status")
2
>>> db.status.get(2, "name")
"in-progress"
>>> db.issue.get(5, "title")
"abuse"
>>> db.issue.find("status", db.status.lookup("in-progress"))
[2, 4, 5]
>>> db.issue.history(5)
[(<Date 2000-06-28.19:09:43>, "ping", "create", {"title": "abuse", "status": 1}),
 (<Date 2000-06-28.19:11:04>, "ping", "set", {"status": 2})]
>>> db.status.history(1)
[(<Date 2000-06-28.19:09:43>, "ping", "link", ("issue", 5, "status")),
 (<Date 2000-06-28.19:11:04>, "ping", "unlink", ("issue", 5, "status"))]
>>> db.status.history(2)
[(<Date 2000-06-28.19:11:04>, "ping", "link", ("issue", 5, "status"))]

For the purposes of journalling, when a Multilink property is set to a new list of nodes, the hyperdatabase compares the old list to the new list. The journal records "unlink" events for all the nodes 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.

4. Roundup Database

The Roundup database layer is implemented on top of the hyperdatabase and mediates calls to the database. Some of the classes in the Roundup database are considered item classes. The Roundup database layer adds detectors and user nodes, and on items it provides mail spools, nosy lists, and superseders.

4.1. Reserved Classes

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

4.1.1. Users

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

hyperdb.Class(db, "user", username=hyperdb.String(),
                          password=hyperdb.String(),
                          address=hyperdb.String())
db.user.setkey("username")

4.1.2. Messages

E-mail messages are represented by hyperdatabase nodes 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") for the sake of the command interface (see below). Attachments are stored separately and associated with "file" nodes. The "msg" class has the definition: 

hyperdb.Class(db, "msg", author=hyperdb.Link("user"),
                         recipients=hyperdb.Multilink("user"),
                         date=hyperdb.Date(),
                         summary=hyperdb.String(),
                         files=hyperdb.Multilink("file"))

The "author" property indicates the author of the message (a "user" node 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.

4.1.3. Files

Submitted files are represented by hyperdatabase nodes 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"). The "file" class has the definition: 

hyperdb.Class(db, "file", user=hyperdb.Link("user"),
                          name=hyperdb.String(),
                          type=hyperdb.String())

The "user" property indicates the user who submitted the file, the "name" property holds the original name of the file, and the "type" property holds the MIME type of the file as received.

4.2. Item Classes

All items have the following standard properties: 

title=hyperdb.String()
messages=hyperdb.Multilink("msg")
files=hyperdb.Multilink("file")
nosy=hyperdb.Multilink("user")
superseder=hyperdb.Multilink("item")

Also, two Date properties named "creation" and "activity" are fabricated by the Roundup database layer. By "fabricated" we mean that no such properties are actually stored in the hyperdatabase, but when properties on items are requested, the "creation" and "activity" properties are made available. 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).

4.3. Interface Specification

The interface to a Roundup database delegates most method calls to the hyperdatabase, except for the following changes and additional methods. 

class Database:
    # Overridden methods:

    def __init__(self, storagelocator, journaltag):
        """When the Roundup database is opened by a particular user,
        the 'journaltag' is the id of the user's "user" node."""

    def getclass(self, classname):
        """This method now returns an instance of either Class or
        ItemClass depending on whether an item class is specified."""

    # New methods:

    def getuid(self):
        """Return the id of the "user" node associated with the user
        that owns this connection to the hyperdatabase."""

class Class:
    # Overridden methods:

    def create(self, **propvalues):
    def set(self, **propvalues):
    def retire(self, nodeid):
        """These operations trigger detectors and can be vetoed.  Attempts
        to modify the "creation" or "activity" properties cause a KeyError.
        """

    # New methods:

    def audit(self, event, detector):
    def react(self, event, detector):
        """Register a detector (see below for more details)."""

class ItemClass(Class):
    # Overridden methods:

    def __init__(self, db, classname, **properties):
        """The newly-created class automatically includes the "messages",
        "files", "nosy", and "superseder" properties.  If the 'properties'
        dictionary attempts to specify any of these properties or a
        "creation" or "activity" property, a ValueError is raised."""

    def get(self, nodeid, propname):
    def getprops(self):
        """In addition to the actual properties on the node, these
        methods provide the "creation" and "activity" properties."""

    # New methods:

    def addmessage(self, nodeid, summary, text):
        """Add a message to an item's mail spool.

        A new "msg" node 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"
        field of the specified item.
        """

    def sendmessage(self, nodeid, 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
        already on the "recipients" list for the message.  These users
        are then added to the message's "recipients" list.
        """

4.4. Default Schema

The default schema included with Roundup turns it into a typical software bug tracker. The database is set up like this: 

pri = Class(db, "priority", name=hyperdb.String(), order=hyperdb.String())
pri.setkey("name")
pri.create(name="critical", order="1")
pri.create(name="urgent", order="2")
pri.create(name="bug", order="3")
pri.create(name="feature", order="4")
pri.create(name="wish", order="5")

stat = Class(db, "status", name=hyperdb.String(), order=hyperdb.String())
stat.setkey("name")
stat.create(name="unread", order="1")
stat.create(name="deferred", order="2")
stat.create(name="chatting", order="3")
stat.create(name="need-eg", order="4")
stat.create(name="in-progress", order="5")
stat.create(name="testing", order="6")
stat.create(name="done-cbb", order="7")
stat.create(name="resolved", order="8")

Class(db, "keyword", name=hyperdb.String())

Class(db, "issue", fixer=hyperdb.Multilink("user"),
                   topic=hyperdb.Multilink("keyword"),
                   priority=hyperdb.Link("priority"),
                   status=hyperdb.Link("status"))

(The "order" property hasn't been explained yet. It gets used by the Web user interface for sorting.)

The above isn't as pretty-looking as the schema specification in the first-stage submission, but it could be made just as easy with the addition of a convenience function like Choice for setting up the "priority" and "status" classes: 

def Choice(name, *options):
    cl = Class(db, name, name=hyperdb.String(), order=hyperdb.String())
    for i in range(len(options)):
        cl.create(name=option[i], order=i)
    return hyperdb.Link(name)

5. Detector Interface

Detectors are Python functions that are triggered on certain kinds of events. The definitions of the functions live in Python modules placed in a directory set aside for this purpose. Importing the Roundup database module also imports all the modules in this directory, and the init() function of each module is called when a database is opened to provide it a chance to register its detectors.

There are two kinds of detectors:

  • an auditor is triggered just before modifying an node
  • a reactor is triggered just after an node has been modified

When the Roundup database is about to perform a create(), set(), or retire() operation, it first calls any auditors that have been registered for that operation on that class. Any auditor may raise a Reject exception to abort the operation.

If none of the auditors raises an exception, the database proceeds to carry out the operation. After it's done, it then calls all of the reactors that have been registered for the operation.

5.1. Interface Specification

The audit() and react() methods register detectors on a given class of nodes. 

class Class:
    def audit(self, event, detector):
        """Register an auditor on this class.

        'event' should be one of "create", "set", or "retire".
        'detector' should be a function accepting four arguments.
        """

    def react(self, event, detector):
        """Register a reactor on this class.

        'event' should be one of "create", "set", or "retire".
        'detector' should be a function accepting four arguments.
        """

Auditors are called with the arguments: 

audit(db, cl, nodeid, newdata)
where db is the database, cl is an instance of Class or ItemClass within the database, and newdata is a dictionary mapping property names to values. For a create() operation, the nodeid argument is None and newdata contains all of the initial property values with which the node is about to be created. For a set() operation, newdata contains only the names and values of properties that are about to be changed. For a retire() operation, newdata is None.

Reactors are called with the arguments: 

react(db, cl, nodeid, olddata)
where db is the database, cl is an instance of Class or ItemClass within the database, and olddata is a dictionary mapping property names to values. For a create() operation, the nodeid argument is the id of the newly-created node and olddata is None. 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.

5.2. Detector Example

Here is an example of detectors written for a hypothetical project-management application, where users can signal approval of a project by adding themselves to an "approvals" list, and a project proceeds when it has three approvals. 

# Permit users only to add themselves to the "approvals" list.

def check_approvals(db, cl, id, newdata):
    if newdata.has_key("approvals"):
        if cl.get(id, "status") == db.status.lookup("approved"):
            raise Reject, "You can't modify the approvals list " \
                          "for a project that has already been approved."
        old = cl.get(id, "approvals")
        new = newdata["approvals"]
        for uid in old:
            if uid not in new and uid != db.getuid():
                raise Reject, "You can't remove other users from the "
                              "approvals list; you can only remove yourself."
        for uid in new:
            if uid not in old and uid != db.getuid():
                raise Reject, "You can't add other users to the approvals "
                              "list; you can only add yourself."

# When three people have approved a project, change its
# status from "pending" to "approved".

def approve_project(db, cl, id, olddata):
    if olddata.has_key("approvals") and len(cl.get(id, "approvals")) == 3:
        if cl.get(id, "status") == db.status.lookup("pending"):
            cl.set(id, status=db.status.lookup("approved"))

def init(db):
    db.project.audit("set", check_approval)
    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 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 patch by setting its status to "applied". 

# Only accept attempts to create new patches that come with patch files.

def check_new_patch(db, cl, id, newdata):
    if not newdata["files"]:
        raise Reject, "You can't submit a new patch without " \
                      "attaching a patch file."
    for fileid in newdata["files"]:
        if db.file.get(fileid, "type") != "text/plain":
            raise Reject, "Submitted patch files must be text/plain."

# When the status is changed from "approved" to "applied", apply the patch.

def apply_patch(db, cl, id, olddata):
    if cl.get(id, "status") == db.status.lookup("applied") and \
        olddata["status"] == db.status.lookup("approved"):
        # ...apply the patch...

def init(db):
    db.patch.audit("create", check_new_patch)
    db.patch.react("set", apply_patch)

6. Command Interface

The command interface is a very simple and minimal interface, intended only for quick searches and checks from the shell prompt. (Anything more interesting can simply be written in Python using the Roundup database module.)

6.1. Interface Specification

A single command, roundup, provides basic access to the hyperdatabase from the command line.

  • roundup get [-list] designator[,designator,...] propname
  • roundup set designator[,designator,...] propname=value ...
  • roundup find [-list] classname propname=value ...

Property values are represented as strings in command arguments and in the printed results:

  • Strings are, well, strings.
  • Date values are printed in the full date format in the local time zone, and accepted in the full format or any of the partial formats explained above.
  • 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 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 results are returned by the roundup get or roundup find commands, they are printed one per line (default) or joined by commas (with the -list) option.

6.2. Usage Example

To find all messages regarding in-progress issues that contain the word "spam", for example, you could execute the following command from the directory where the database dumps its files: 

shell% for issue in `roundup find issue status=in-progress`; do
> grep -l spam `roundup get $issue messages`
> done
msg23
msg49
msg50
msg61
shell%

Or, using the -list option, this can be written as a single command: 

shell% grep -l spam `roundup get \
    \`roundup find -list issue status=in-progress\` messages`
msg23
msg49
msg50
msg61
shell%

7. E-mail User Interface

The Roundup system must be assigned an e-mail address at which to receive mail. Messages should be piped to the Roundup mail-handling script by the mail delivery system (e.g. using an alias beginning with "|" for sendmail).

7.1. Message Processing

Incoming messages are examined for multiple parts. In a multipart/mixed message or part, each subpart is extracted and examined. In a multipart/alternative message or part, we look for a text/plain subpart and ignore the other parts. The text/plain subparts are assembled to form the textual body of the message, to be stored in the file associated with a "msg" class node. Any parts of other types are each stored in separate files and given "file" class nodes that are linked to the "msg" node.

The "summary" property on message nodes 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 non-quoting section becomes the summary of the message.

All of the addresses in the To: and Cc: headers of the incoming message are looked up among the user nodes, and 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 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 no passwords.

The subject line of the incoming message is examined to determine whether the message is an attempt to create a new item or to discuss an existing item. A designator enclosed in square brackets is sought as the first thing on the subject line (after skipping any "Fwd:" or "Re:" prefixes).

If an item designator (class name and id number) is found there, the newly created "msg" node is added to the "messages" property for that item, and any new "file" nodes are added to 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.

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

7.2. Nosy Lists

A standard detector is provided that watches for additions to the "messages" property. When a new message is added, the detector sends it to all the users on the "nosy" list for the item that are not already on the "recipients" list of the message. Those users are then appended to the "recipients" property on the message, so multiple copies of a message are never sent to the same user. The journal recorded by the hyperdatabase on the "recipients" property then provides a log of when the message was sent to whom.

7.3. Setting Properties

The e-mail interface also provides a simple way to set properties on items. At the end of the subject line, propname=value pairs can be specified in square brackets, using the same conventions as for the roundup set shell command.

8. Web User Interface

The web interface is provided by a CGI script that can be run under any web server. A simple web server can easily be built on the standard CGIHTTPServer module, and should also be included in the distribution for quick out-of-the-box deployment.

The user interface is constructed from a number of template files containing mostly HTML. Among the HTML tags in templates are interspersed some nonstandard tags, which we use as placeholders to be replaced by properties and their values.

8.1. Views and View Specifiers

There are two main kinds of views: index views and item views. An index view displays a list of items of a particular class, optionally sorted and filtered as requested. An item view presents the properties of a particular item for editing and displays the message spool for the item.

A view specifier is a string that specifies all the options needed to construct a particular view. It goes after the URL to the Roundup CGI script or the web server to form the complete URL to a view. When the result of selecting a link or submitting a form takes the user to a new view, the Web browser should be redirected to a canonical location containing a complete view specifier so that the view can be bookmarked.

8.2. Displaying Properties

Properties appear in the user interface in three contexts: in indices, in editors, and as filters. For each type of property, there are several display possibilities. For example, in an index view, a string property may just be printed as a plain string, but in an editor view, that property should be displayed in an editable field.

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

Displayer functions are triggered by <display> tags in templates. The call attribute of the tag provides a Python expression for calling the displayer function. The three standard arguments are inserted in front of the arguments given. For example, the occurrence of 

    <display call="plain('status', max=30)">
in a template triggers a call to 
    plain(db, "issue", 13, "status", max=30)
when displaying item 13 in the "issue" class. The displayer functions can accept extra arguments to further specify details about the widgets that should be generated. By defining new displayer functions, the user interface can be highly customized.

Some of the standard displayer functions include:

  • 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 ids if the linked class has no key property)
  • field: display a property like the plain displayer above, but in a text field to be edited
  • 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 item views on those nodes
  • count: for a Multilink property, display a count of the number of links in the list
  • reldate: display a Date property in terms of an interval relative to the current date (e.g. "+ 3w", "- 2d").
  • download: show a Link("file") or Multilink("file") property using links that allow you to download files
  • checklist: for a Link or Multilink property, display checkboxes for the available choices to permit filtering

8.3. Index Views

An index view contains two sections: a filter section and an index section. The filter section provides some widgets for selecting which items appear in the index. The index section is a table of items.

8.3.1. Index View Specifiers

An index view specifier looks like this (whitespace has been added for clarity): 

/issue?status=unread,in-progress,resolved&
        topic=security,ui&
        :group=+priority&
        :sort=-activity&
        :filters=status,topic&
        :columns=title,status,fixer

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 are displayed. The filter part consists of all the other query parameters, and it determines the criteria by which nodes 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.

The filter part selects the union of the sets of items with values matching any 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 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 by activity, arranged in descending order. The filter section shows filters for the "status" and "topic" properties, and the table includes columns for the "title", "status", and "fixer" properties.

Associated with each item class is a default layout specifier. The layout specifier in the above example is the default layout to be provided with the default bug-tracker schema described above in section 4.4.

8.3.2. Filter Section

The template for a filter section provides the filtering widgets at the top of the index view. Fragments enclosed in <property>...</property> tags are included or omitted depending on whether the view specifier requests a filter for a particular property.

Here's a simple example of a filter template. 

<property name=status>
    <display call="checklist('status')">
</property>
<br>
<property name=priority>
    <display call="checklist('priority')">
</property>
<br>
<property name=fixer>
    <display call="menu('fixer')">
</property>

8.3.3. Index Section

The template for an index section describes one row of the index table. Fragments enclosed in <property>...</property> tags are included or omitted depending on whether the view specifier requests a column for a particular property. The table cells should contain <display> tags to display the values of the item's properties.

Here's a simple example of an index template. 

<tr>
    <property name=title>
        <td><display call="plain('title', max=50)"></td>
    </property>
    <property name=status>
        <td><display call="plain('status')"></td>
    </property>
    <property name=fixer>
        <td><display call="plain('fixer')"></td>
    </property>
</tr>

8.3.4. Sorting

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 sorted according to how many links are present.

8.4. Item Views

An item view contains an editor section and a spool section. At the top of an item view, links to superseding and superseded items are always displayed.

8.4.1. Item View Specifiers

An item view specifier is simply the item's designator: 

/patch23

8.4.2. Editor Section

The editor section is generated from a template containing <display> tags to insert the appropriate widgets for editing properties.

Here's an example of a basic editor template. 

<table>
<tr>
    <td colspan=2>
        <display call="field('title', size=60)">
    </td>
</tr>
<tr>
    <td>
        <display call="field('fixer', size=30)">
    </td>
    <td>
        <display call="menu('status')>
    </td>
</tr>
<tr>
    <td>
        <display call="field('nosy', size=30)">
    </td>
    <td>
        <display call="menu('priority')>
    </td>
</tr>
<tr>
    <td colspan=2>
        <display call="note()">
    </td>
</tr>
</table>

As shown in the example, the editor template can also request the display of a "note" field, which is a text area for entering a note to go along with a change.

When a change is submitted, the system automatically generates a message describing the changed properties. The message displays all of the property values on the item and indicates which ones have changed. An example of such a message might be this: 

title: Polly Parrot is dead
priority: critical
status: unread -> in-progress
fixer: (none)
keywords: parrot,plumage,perch,nailed,dead

If a note is given in the "note" field, the note is appended to the description. The message is then added to the item's message spool (thus triggering the standard detector to react by sending out this message to the nosy list).

8.4.3. Spool Section

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 message takes you to its content.

9. Deployment Scenarios

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 that maintains requirement specifications, catalogs bugs, and manages submitted patches, where patches could be linked to the bugs and requirements they address.

10. Acknowledgements

My thanks are due to Christy Heyl for reviewing and contributing suggestions to this paper and motivating me to get it done, and to Jesse Vincent, Mark Miller, Christopher Simons, Jeff Dunmall, Wayne Gramlich, and Dean Tribble for their assistance with the first-round submission.

   [Home]       [FAQ]       [License]       [Rules]       [Configure]       [Build]       [Test]       [Track]       [Resources]       [Archives]   

Last modified 2001/04/06 11:50:59.9063 US/Mountain
code-b3b483e0fd5e/doc/user_guide.stx0000644000000000000000000003751107437047562015477 0ustar 00000000000000User Guide ========== Command Line Tool ----------------- Usage: ``roundup-admin [-i instance home] [-u login] [-c] `` Options: -i instance home specify the issue tracker "home directory" to administer -u the ``user[:password]`` to use for commands -c when outputting lists of data, comma-separate them +-----------------------------------------------------------------------------+ | Command Help | +=============+===============================================================+ |commit |Usage: commit | | |The changes made during an interactive session are not | | |automatically written to the database - they must be committed | | |using this command. | | | | | |One-off commands on the command-line are automatically | | |committed if they are successful. | +-------------+---------------------------------------------------------------+ |create |Usage: create classname property=value ... | | |This creates a new entry of the given class using the property | | |name=value arguments provided on the command line after the | | |"create" command. | +-------------+---------------------------------------------------------------+ |display |Usage: display designator | | |This lists the properties and their associated values for the | | |given node. | +-------------+---------------------------------------------------------------+ |export |Usage: export class[,class] destination dir | | |This action exports the current data from the database into | | |tab-separated-value files that are placed in the nominated | | |destination | | |directory. The journals are not exported. | +-------------+---------------------------------------------------------------+ |find |Usage: find classname propname=value ... | | |Find the nodes 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. | +-------------+---------------------------------------------------------------+ |get |Usage: get property designator[,designator]* | | |Retrieves the property value of the nodes specified by the | | |designators. | +-------------+---------------------------------------------------------------+ |help |Usage: help topic | | |commands -- list commands | | |x -- help specific to a command | | |initopts -- init command options | | |all -- all available help | +-------------+---------------------------------------------------------------+ |history |Usage: history designator | | |Lists the journal entries for the node 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 | | |added to | | |the existing database - if you want to create a new database | | |using the | | |imported data, then create a new database (or, tediously, | | |retire all | | |the old data.) | +-------------+---------------------------------------------------------------+ |initialise |Usage: initialise [template [backend [admin password]]] | | |The command will prompt for the instance home directory (if not| | |supplied | | |through INSTANCE HOME or the -i option. The template, backend | | |and admin | | |password may be specified on the command-line as arguments, in | | |that | | |order. | | | | | |See also initopts help. | +-------------+---------------------------------------------------------------+ |list |Usage: list classname [property] | | |Lists all instances 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 | | |retrieved by | | |the list or find commands, and its key value may be re-used. | +-------------+---------------------------------------------------------------+ |rollback |Usage: rollback | | |The changes made during an interactive session are not | | |automatically written to the database - they must be committed | | |manually. This command undoes all those changes, so a commit | | |immediately after would make no changes to the database. | +-------------+---------------------------------------------------------------+ |set |Usage: set designator[,designator]* propname=value ... | | |Sets the property to the value for all designators given. | +-------------+---------------------------------------------------------------+ |specification|Usage: specification classname | | |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 | | |not | | |specified, all properties are displayed. By default, the column| | |widths | | |are the width of the property names. The width may be | | |explicitly defined | | |by defining the property as "name:width". For example:: | | | | | | roundup> table priority id,name:10 | | | Id Name | | | 1 fatal-bug | | | 2 bug | | | 3 usability | | | 4 feature | +-------------+---------------------------------------------------------------+ 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 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``". A designator is a classname and a nodeid concatenated, eg. bug1, user10, ... Property values are represented as strings in command arguments and in the printed results: - Strings are, well, strings. - Password values will display as their encoded value. - Date values are printed in the full date format in the local time zone, and accepted in the full format or any of the partial formats explained below.:: Input of... Means... "2000-04-17.03:45" 2000-04-17.08:45:00 "2000-04-17" 2000-04-17.00:00:00 "01-25" yyyy-01-25.00:00:00 "08-13.22:13" yyyy-08-14.03:13:00 "11-07.09:32:43" yyyy-11-07.14:32:43 "14:25" yyyy-mm-dd.19:25:00 "8:47:11" yyyy-mm-dd.13:47:11 "." "right now" - Link values are printed as node designators. When given as an argument, node designators and key strings are both accepted. - Multilink values are printed as lists of node designators joined by commas. 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. 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 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). Where the command changes data, a login name/password is required. The login may be specified as either "``name``" or "``name:password``". - ``ROUNDUP_LOGIN`` environment variable - the "``-u``" command-line option If either the name or password is not supplied, they are obtained from the command-line. Web Interface ------------- Index views may be modified by the following arguments: +-----------+--------------------------------------------------------------+ | :sort | sort by prop name, optionally preceeded with '-' | | | to give descending or nothing for ascending sorting. | +-----------+--------------------------------------------------------------+ | :group | group by prop name, optionally preceeded with '-' or | | | to sort in descending or nothing for ascending order. | +-----------+--------------------------------------------------------------+ | :filter | selects which props should be displayed in the filter | | | section. Default is all. | +-----------+--------------------------------------------------------------+ | :columns | selects the columns that should be displayed. | | | Default is all. | +-----------+--------------------------------------------------------------+ | propname | selects the values the node properties given by propname | | | must have (very basic search/filter). | +-----------+--------------------------------------------------------------+ Not sure what to put in here... E-Mail Gateway -------------- Performing Actions ~~~~~~~~~~~~~~~~~~ The subject line of the incoming message is examined to determine whether the message is an attempt to create a new item or to discuss an existing item. A designator enclosed in square brackets is sought as the first thing on the subject line (after skipping any "Fwd:" or "Re:" prefixes). If an item designator (class name and id number) is found there, the newly created "msg" node is added to the "messages" property for that item, and any new "file" nodes are added to 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. Setting Properties ~~~~~~~~~~~~~~~~~~ The e-mail interface also provides a simple way to set properties on items. At the end of the subject line, propname=value pairs can be specified in square brackets, using the same conventions as for the roundup set shell command. explanatory message given in the exception. Message content ~~~~~~~~~~~~~~~ Incoming messages are examined for multiple parts: * 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. * 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 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 non-quoting section becomes the summary of the message. Address handling ~~~~~~~~~~~~~~~~ All of the addresses in the To: and Cc: headers of the incoming message are looked up among the user nodes, 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 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 no passwords. Triggers ~~~~~~~~ Both cases may trigger detectors (in the first case we are calling the set() method to add the message to the item's spool; in the second case we are calling the create() method to create a new node). If an auditor raises an exception, the original message is bounced back to the sender with the Nosy Lists :::::::::: A standard detector is provided that watches for additions to the "messages" property. When a new message is added, the detector sends it to all the users on the "nosy" list for the item that are not already on the "recipients" list of the message. Those users are then appended to the "recipients" property on the message, so multiple copies of a message are never sent to the same user. The journal recorded by the hyperdatabase on the "recipients" property then provides a log of when the message was sent to whom.