Mercurial > p > roundup > code

comparison doc/index.html @ 277:20fed9cad7b4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
more doc
author Richard Jones <richard@users.sourceforge.net>
date Wed, 10 Oct 2001 01:47:55 +0000
parents 85908e1f46ad
children 231a031e4765
comparison
equal deleted inserted replaced
276:9fa86988375f 277:20fed9cad7b4
155 <br>submissions of issues 155 <br>submissions of issues
156 <li>ADMIN_EMAIL - roundup-admin@MAIL_DOMAIN 156 <li>ADMIN_EMAIL - roundup-admin@MAIL_DOMAIN
157 <br>roundup's internal use (problems, etc) 157 <br>roundup's internal use (problems, etc)
158 </ol> 158 </ol>
159 159
160 <em>Note:</em>
161 We run the instance as group "issue_tracker" and add the mail and web user
162 ("mail" and "apache" on our RedHat 7.1 system) to that group, as well as
163 any admin people.
164
165
166 <h2><a name="startweb">E-Mail Interface</a></h2> 160 <h2><a name="startweb">E-Mail Interface</a></h2>
167 Set up a mail alias called "issue_tracker" as: 161 Set up a mail alias called "issue_tracker" as:
168 <blockquote> 162 <blockquote>
169 <tt>|/usr/bin/python /usr/local/bin/roundup-mailgw 163 <tt>|/usr/bin/python /usr/local/bin/roundup-mailgw
170 &lt;instance_home&gt;</tt> 164 &lt;instance_home&gt;</tt>
245 (substituting instance_home for the directory you want to use):<br> 239 (substituting instance_home for the directory you want to use):<br>
246 <pre> 240 <pre>
247 mkdir instance_home 241 mkdir instance_home
248 chown issue_tracker:issue_tracker instance_home 242 chown issue_tracker:issue_tracker instance_home
249 chmod g+rwxs instance_home 243 chmod g+rwxs instance_home
250 chmod o-rwx instance_home
251 roundup-admin -i instance_home init 244 roundup-admin -i instance_home init
252 </pre> 245 </pre>
253 <li>Now, edit the /etc/group line for issue_tracker so it includes the unix 246 <li>Now, edit the /etc/group line for the issue_tracker group so it includes
254 logins of all the users who are going to administer your roundup instance. 247 the unix logins of all the users who are going to administer your roundup
248 instance. If you're running the web or mail gateways, then be sure to
249 include those users in the group too (on some Linux systems, these
250 users are "www" or "apache" and "mail".)
255 </ol> 251 </ol>
256 252
257 <dt><strong>E-Mail interface</strong> 253 <dt><strong>E-Mail interface</strong>
258 <dd>Users are identified by e-mail address - a new user entry will be 254 <dd>Users are identified by e-mail address - a new user entry will be
259 created for any e-mail address that is not recognised, so users are 255 created for any e-mail address that is not recognised, so users are
468 464
469 <strong>Not sure what to put in here...</strong> 465 <strong>Not sure what to put in here...</strong>
470 466
471 <h2><a name="mail">E-Mail Gateway</a></h2> 467 <h2><a name="mail">E-Mail Gateway</a></h2>
472 468
469 <h3>Performing Actions</h3>
470 The subject line of the incoming message is examined to determine whether
471 the message is an attempt to create a new item or to discuss an existing
472 item. A designator enclosed in square brackets is sought as the first thing
473 on the subject line (after skipping any "Fwd:" or "Re:" prefixes).
474 <p>
475 If an item designator (class name and id number) is found there, the newly
476 created "msg" node is added to the "messages" property for that item, and
477 any new "file" nodes are added to the "files" property for the item.
478 <p>
479 If just an item class name is found there, we attempt to create a new item
480 of that class with its "messages" property initialized to contain the new
481 "msg" node and its "files" property initialized to contain any new "file"
482 nodes.
483
484 <h3>Setting Properties</h3>
485 The e-mail interface also provides a simple way to set
486 properties on items. At the end of the subject line,
487 <em>propname</em><tt>=</tt><em>value</em> pairs can be
488 specified in square brackets, using the same conventions
489 as for the <tt>roundup&nbsp;set</tt> shell command.
490 explanatory message given in the exception.
491
492 <h3>Message content</h3>
473 Incoming messages are examined for multiple parts: 493 Incoming messages are examined for multiple parts:
474 <ul> 494 <ul>
475 <li>In a multipart/mixed message or part, each subpart is extracted and 495 <li>In a multipart/mixed message or part, each subpart is extracted and
476 examined. The text/plain subparts are assembled to form the textual 496 examined. The text/plain subparts are assembled to form the textual
477 body of the message, to be stored in the file associated with a "msg" 497 body of the message, to be stored in the file associated with a "msg"
479 and given "file" class nodes that are linked to the "msg" node. 499 and given "file" class nodes that are linked to the "msg" node.
480 <li>In a multipart/alternative message or part, we look for a text/plain 500 <li>In a multipart/alternative message or part, we look for a text/plain
481 subpart and ignore the other parts. 501 subpart and ignore the other parts.
482 </ul> 502 </ul>
483 503
484 <h3>Message content summary</h3> 504 <h4>Message summary</h4>
485 The "summary" property on message nodes is taken from the first non-quoting 505 The "summary" property on message nodes is taken from the first non-quoting
486 section in the message body. The message body is divided into sections by 506 section in the message body. The message body is divided into sections by
487 blank lines. Sections where the second and all subsequent lines begin with 507 blank lines. Sections where the second and all subsequent lines begin with
488 a "&gt;" or "|" character are considered "quoting sections". The first line of 508 a "&gt;" or "|" character are considered "quoting sections". The first line of
489 the first non-quoting section becomes the summary of the message. 509 the first non-quoting section becomes the summary of the message.
498 address. (The web interface does not permit logins for users with no 518 address. (The web interface does not permit logins for users with no
499 passwords.) If we prefer to reject mail from outside sources, we can simply 519 passwords.) If we prefer to reject mail from outside sources, we can simply
500 register an auditor on the "user" class that prevents the creation of user 520 register an auditor on the "user" class that prevents the creation of user
501 nodes with no passwords. 521 nodes with no passwords.
502 522
503 <h3>Performing Actions</h3>
504 The subject line of the incoming message is examined to determine whether
505 the message is an attempt to create a new item or to discuss an existing
506 item. A designator enclosed in square brackets is sought as the first thing
507 on the subject line (after skipping any "Fwd:" or "Re:" prefixes).
508
509 If an item designator (class name and id number) is found there, the newly
510 created "msg" node is added to the "messages" property for that item, and
511 any new "file" nodes are added to the "files" property for the item.
512
513 If just an item class name is found there, we attempt to create a new item
514 of that class with its "messages" property initialized to contain the new
515 "msg" node and its "files" property initialized to contain any new "file"
516 nodes.
517
518 <h3>Triggers</h3> 523 <h3>Triggers</h3>
519 Both cases may trigger detectors (in the first case we are calling the 524 Both cases may trigger detectors (in the first case we are calling the
520 set() method to add the message to the item's spool; in the second case we 525 set() method to add the message to the item's spool; in the second case we
521 are calling the create() method to create a new node). If an auditor raises 526 are calling the create() method to create a new node). If an auditor raises
522 an exception, the original message is bounced back to the sender with the 527 an exception, the original message is bounced back to the sender with the
523 explanatory message given in the exception. 528
529 <h4>Nosy Lists</h4>
530 A standard detector is provided that watches for additions
531 to the "messages" property. When a new message is added, the
532 detector sends it to all the users on the "nosy" list for the
533 item that are not already on the "recipients" list of the
534 message. Those users are then appended to the "recipients"
535 property on the message, so multiple copies of a message
536 are never sent to the same user. The journal recorded by
537 the hyperdatabase on the "recipients" property then provides
538 a log of when the message was sent to whom.
524 539
525 <p><hr> 540 <p><hr>
526 <h1><a name="custom">Customising Roundup</a></h1> 541 <h1><a name="custom">Customising Roundup</a></h1>
527 542
528 Instances have the following structure: 543 Instances have the following structure:
637 issue = IssueClass(db, "issue", assignedto=Link("user"), 652 issue = IssueClass(db, "issue", assignedto=Link("user"),
638 topic=Multilink("keyword"), priority=Link("priority"), status=Link("status")) 653 topic=Multilink("keyword"), priority=Link("priority"), status=Link("status"))
639 issue.setkey('title') 654 issue.setkey('title')
640 </pre> 655 </pre>
641 656
642 <h3>Class, FileClass, IssueClass - creating a new information store</h3> 657 <h3>Classes and Properties - creating a new information store</h3>
643 A <em>Class</em> defines a particular class (or type) of data that will be 658 In the instance above, we've defined 7 <em>classes</em> of information:
644 stored in the database. In the instance above, we've defined 7 classes of
645 information:
646 <dl> 659 <dl>
647 <dt><strong>priority</strong> 660 <dt><strong>priority</strong>
648 <dd>Defines the possible levels of urgency for issues. 661 <dd>Defines the possible levels of urgency for issues.
649 <dt><strong>status</strong> 662 <dt><strong>status</strong>
650 <dd>Defines the possible states of processing the issue may be in. 663 <dd>Defines the possible states of processing the issue may be in.
659 <dd>Initially empty, will all files attached to issues. 672 <dd>Initially empty, will all files attached to issues.
660 <dt><strong>issue</strong> 673 <dt><strong>issue</strong>
661 <dd>Initially emtyp, this is where the issue information is stored. 674 <dd>Initially emtyp, this is where the issue information is stored.
662 </dl> 675 </dl>
663 <p> 676 <p>
664 We define the "priority" and "status" classes to allow two things: reduction in the 677 We define the "priority" and "status" classes to allow two things: reduction
665 amount of information stored on the issue and more powerful, accurate 678 in the amount of information stored on the issue and more powerful, accurate
666 searching of issues by priority and status. By only requiring a link on 679 searching of issues by priority and status. By only requiring a link on
667 the issue (which is stored as a single number) we reduce the chance 680 the issue (which is stored as a single number) we reduce the chance
668 that someone mis-types a priority or status - or simply makes a new one 681 that someone mis-types a priority or status - or simply makes a new one
669 up. 682 up.
670 <p> 683
671 684 <h4>Class and Nodes</h4>
672 <strong>Class</strong> 685 A <em>Class</em> defines a particular class (or type) of data that will be
673 <br> 686 stored in the database. A class comprises one or more properties, which
674 Class is the basic store of information. 687 given the information about the class nodes.
675 688 <p>
676 <p> 689 The actual data entered into the database, using <em>class</em>.create()
677 A class is comprised of one or more properties of the following type: 690 are called <em>nodes</em>. They have a special immutable property called
691 id. We sometimes refer to this as the <em>nodeid</em>.
692
693
694 <h4>Properties</h4>
695 A Class is comprised of one or more <em>properties</em> of the following types:
678 696
679 <ul> 697 <ul>
680 <li><em>String</em> properties are for storing arbitrary-length 698 <li><em>String</em> properties are for storing arbitrary-length
681 strings. 699 strings.
682 700
693 711
694 <li>A <em>Multilink</em> property refers to possibly many nodes 712 <li>A <em>Multilink</em> property refers to possibly many nodes
695 in a specified class. The value is a list of integers. 713 in a specified class. The value is a list of integers.
696 </ul> 714 </ul>
697 715
698 <p> 716 <h4>FileClass</h4>
699
700 <strong>FileClass</strong>
701 <br>
702 FileClasses save their "content" attribute off in a separate file from the 717 FileClasses save their "content" attribute off in a separate file from the
703 rest of the database. This reduces the number of large entries in the 718 rest of the database. This reduces the number of large entries in the
704 database, which generally makes databases more efficient, and also allows 719 database, which generally makes databases more efficient, and also allows
705 us to use command-line tools to operate on the files. They are stored in 720 us to use command-line tools to operate on the files. They are stored in
706 the files sub-directory of the db directory in your instance. 721 the files sub-directory of the db directory in your instance.
707 722
708 <p> 723 <h4>IssueClass</h4>
709
710 <strong>IssueClass</strong>
711 <br>
712 IssueClasses automatically include the "messages", "files", "nosy", and 724 IssueClasses automatically include the "messages", "files", "nosy", and
713 "superseder" properties. 725 "superseder" properties.
714 <p> 726 <p>
715 The messages and files properties list the links to the messages and files 727 The messages and files properties list the links to the messages and files
716 related to the issue. The nosy property is a list of links to users who 728 related to the issue. The nosy property is a list of links to users who
720 issue which has superceded this one. 732 issue which has superceded this one.
721 <p> 733 <p>
722 They also have the dynamically generated 734 They also have the dynamically generated
723 "creation", "activity" and "creator" properties. 735 "creation", "activity" and "creator" properties.
724 <p> 736 <p>
725 The value of the "creation" property is the date when an item was created, 737 The value of the "creation" property is the date when a node was created,
726 and the value of the "activity" property is the date when any property on 738 and the value of the "activity" property is the date when any property on
727 the item was last edited (equivalently, these are the dates on the first 739 the node was last edited (equivalently, these are the dates on the first
728 and last records in the item's journal). The "creator" property holds a 740 and last records in the node's journal). The "creator" property holds a
729 link to the user that created the issue. 741 link to the user that created the issue.
730 742
731 <h4>setkey(property)</h4> 743 <h4>setkey(property)</h4>
732 Select a String property of the class to be the key property. The key 744 Select a String property of the class to be the key property. The key
733 property muse be unique, and allows references to the items in the class by 745 property muse be unique, and allows references to the nodes in the class by
734 the content of the key property. That is, we can refer to users by their 746 the content of the key property. That is, we can refer to users by their
735 username, e.g. let's say that there's an issue in roundup, issue 23. There's 747 username, e.g. let's say that there's an issue in roundup, issue 23. There's
736 also a user, richard who happens to be user 2. To assign an issue to him, 748 also a user, richard who happens to be user 2. To assign an issue to him,
737 we could do either of: 749 we could do either of:
738 <p> 750 <p>
744 assignedto=richard</tt></blockquote> 756 assignedto=richard</tt></blockquote>
745 <p> 757 <p>
746 Note, the same thing can be done in the web and e-mail interfaces. 758 Note, the same thing can be done in the web and e-mail interfaces.
747 759
748 <h4>create(information)</h4> 760 <h4>create(information)</h4>
749 Create an item in the database. This is generally used to create items in 761 Create a node in the database. This is generally used to create nodes in
750 the "definitional" classes like "priority" and "status". 762 the "definitional" classes like "priority" and "status".
763
751 764
752 <h2><a name="custweb">Web Interface</a></h2> 765 <h2><a name="custweb">Web Interface</a></h2>
753 766
754 The web interface works behind the cgi-bin/roundup.cgi or roundup-server 767 The web interface works behind the cgi-bin/roundup.cgi or roundup-server
755 scripts. In both cases, the scripts determine which instance is being 768 scripts. In both cases, the scripts determine which instance is being
819 SELECT fields and Multilinks use SELECT MULTIPLE fields. 832 SELECT fields and Multilinks use SELECT MULTIPLE fields.
820 <p> 833 <p>
821 <em>Options:</em><br> 834 <em>Options:</em><br>
822 size (number) - width of TEXT fields.<br> 835 size (number) - width of TEXT fields.<br>
823 height (number) - number of nows in SELECT MULTIPLE tags.<br> 836 height (number) - number of nows in SELECT MULTIPLE tags.<br>
824 showid (boolean) - true includes the id of linked items in the SELECT 837 showid (boolean) - true includes the id of linked nodes in the SELECT
825 MULTIPLE fields. 838 MULTIPLE fields.
826 </td></tr> 839 </td></tr>
827 840
828 <tr><td valign="top"><strong>menu</strong></td> 841 <tr><td valign="top"><strong>menu</strong></td>
829 <td>For a Links and Multilinks, display the same field as would be 842 <td>For a Links and Multilinks, display the same field as would be
879 <td>Display the special notes field, which is a text area for entering a 892 <td>Display the special notes field, which is a text area for entering a
880 note to go along with a change. 893 note to go along with a change.
881 </td></tr> 894 </td></tr>
882 895
883 <tr><td valign="top"><strong>list</strong></td> 896 <tr><td valign="top"><strong>list</strong></td>
884 <td>List the items specified by property using the standard index for 897 <td>List the nodes specified by property using the standard index for
885 the class. 898 the class.
886 <p> 899 <p>
887 <em>Arguments:</em><br> 900 <em>Arguments:</em><br>
888 property (property name) - the property to use. 901 property (property name) - the property to use.
889 </td></tr> 902 </td></tr>
1124 Go Ping, you rock! Also, go Bizar Software for letting me implement this 1137 Go Ping, you rock! Also, go Bizar Software for letting me implement this
1125 system on their time. 1138 system on their time.
1126 1139
1127 <p>&nbsp;</p> 1140 <p>&nbsp;</p>
1128 <hr> 1141 <hr>
1129 $Id: index.html,v 1.12 2001-10-09 07:31:02 richard Exp $ 1142 $Id: index.html,v 1.13 2001-10-10 01:47:55 richard Exp $
1130 <p>&nbsp;</p> 1143 <p>&nbsp;</p>
1131 1144
1132 </body></html> 1145 </body></html>
1133 1146
Roundup Issue Tracker: http://roundup-tracker.org/