![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/user_guide.txt b/doc/user_guide.txt
index 8925326f7adba75f580ac082c7d0fe2442a5fe25..055c5da5cc14ef162bf7189f02d31b4a5d5603a7 100644 (file)
--- a/doc/user_guide.txt
+++ b/doc/user_guide.txt
User Guide
==========
-:Version: $Revision: 1.23 $
-
.. contents::
-Note: this document will refer to *issues* as the primary store of
-information in the tracker. This is the default of the classic template,
-but may vary in any given installation.
+.. hint::
+ This document will refer to *issues* as the primary store of
+ information in the tracker. This is the default of the classic template,
+ but may vary in any given installation.
Your Tracker in a Nutshell
reports and features, the class is "issue", and for users the class is
"user".
-Each item in the tracker has an id number that identifies it along with
+Each item in the tracker has an ID number that identifies it along with
its item class. To identify a particular issue or user, we combine the
class with the number to create a unique label, so that user 1 (who,
incidentally, is *always* the "admin" user) is referred to as "user1".
Issue number 315 is referred to as "issue315". We call that label the
item's *designator*.
+Items in the database are never deleted, they're just "retired". You
+can still refer to them by ID - hence removing an item won't break
+references to the item. It's just that the item won't appear in any
+listings.
+
Accessing the Tracker
---------------------
3. using the `command line tool`_.
The last is usually only used by administrators. Most users will use the
-web and email interfaces. All three are explained below.
+web and e-mail interfaces. All three are explained below.
Issue life cycles in Roundup
----------------------------
-New issues may be submitted via the web or email.
+New issues may be submitted via the web or e-mail.
By default, the issue will have the status "unread". If another message
is received for the issue, its status will change to "chatting".
The "home" page for a tracker will generally display all issues which
-are not "resolved.
+are not "resolved".
If an issue is closed, and a new message is received then it'll be
reopened to the state of "chatting".
+The full set of **prority** and **status** values are:
+
+=========== =====================================
+Priority Description
+=========== =====================================
+"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 Description
+============= =====================================
+"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
+============= =====================================
+
Entering values in your Tracker
-------------------------------
All interfaces to your tracker use the same format for entering values.
This means the web interface for entering a new issue, the web interface
-for searching issues, the email interface and even the command-line
+for searching issues, the e-mail interface and even the command-line
administration tool.
Constrained (link and multilink) properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Fields like "Assigned To" and "Topics" hold references to items in other
+Fields like "Assigned To" and "Keywords" hold references to items in other
classes ("user" and "keyword" in those two cases.)
Sometimes, the selection is done through a menu, like in the "Assigned
match issues that are not assigned to a user.
``assignedto=2,3,40``
match issues that are assigned to users 2, 3 or 40.
-``topic=user interface``
- match issues with the keyword "user interface" in their topic list
-``topic=web interface,email interface``
- match issues with the keyword "web interface" or "email interface" in
- their topic list
-``topic=-1``
- match issues with no topics set
+``keyword=user interface``
+ match issues with the keyword "user interface" in their keyword list
+``keyword=web interface,e-mail interface``
+ match issues with the keyword "web interface" or "e-mail interface" in
+ their keyword list
+``keyword=-1``
+ match issues with no keywords set
Date properties
~~~~~~~~~~~~~~~
-Some fields in the search page (e.g. "Activity" or "Creation date") hold
-dates. A plain date entered as a search field will match that date
+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.
+
+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.
+
+- "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"
+
+
+When searching, a plain date entered as a search field will match that date
exactly in the database. We may also accept ranges of dates. You can
specify range of dates in one of two formats:
For example, if you enter string "from 9:00" to "Creation date" field,
roundup will find all issues, that were created today since 9 AM.
+The ``<value>`` may also be an interval, as described in the next section.
Searching of "-2m; -1m" on activity field gives you issues which were
active between period of time since 2 months up-till month ago.
-Other possible examples (consider local time is Sat Mar 8 22:07:48
-2003)::
-
- >>> Range("from 2-12 to 4-2")
- <Range from 2003-02-12.00:00:00 to 2003-04-02.00:00:00>
-
- >>> Range("FROM 18:00 TO +2m")
- <Range from 2003-03-08.18:00:00 to 2003-05-08.20:07:48>
+Other possible examples (consider local time is 2003-03-08.22:07:48):
+
+- "from 2-12 to 4-2" means
+ <Range from 2003-02-12.00:00:00 to 2003-04-02.00:00:00>
+- "FROM 18:00 TO +2m" means
+ <Range from 2003-03-08.18:00:00 to 2003-05-08.20:07:48>
+- "12:00;" means
+ <Range from 2003-03-08.12:00:00 to None>
+- "tO +3d" means
+ <Range from None to 2003-03-11.20:07:48>
+- "2002-11-10; 2002-12-12" means
+ <Range from 2002-11-10.00:00:00 to 2002-12-12.00:00:00>
+- "; 20:00 +1d" means
+ <Range from None to 2003-03-09.20:00:00>
+- "2003" means
+ <Range from 2003-01-01.00:00:00 to 2003-12-31.23:59:59>
+- "2003-04" means
+ <Range from 2003-04-01.00:00:00 to 2003-04-30.23:59:59>
- >>> Range("12:00;")
- <Range from 2003-03-08.12:00:00 to None>
-
- >>> Range("tO +3d")
- <Range from None to 2003-03-11.20:07:48>
-
- >>> Range("2002-11-10; 2002-12-12")
- <Range from 2002-11-10.00:00:00 to 2002-12-12.00:00:00>
- >>> Range("; 20:00 +1d")
- <Range from None to 2003-03-09.20:00:00>
+Interval properties
+~~~~~~~~~~~~~~~~~~~
- >>> Range("2003")
- <Range from 2003-01-01.00:00:00 to 2003-12-31.23:59:59>
+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).
- >>> Range("2003-04")
- <Range from 2003-04-01.00:00:00 to 2003-04-30.23:59:59>
-
+- "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
-Interval properties
-~~~~~~~~~~~~~~~~~~~
-XXX explain...
+Simple support for collision detection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-When searching on interval properties use the same syntax as for dates.
+Item edit pages remember when the item was last edited. When a form is
+submitted, the user will be informed if someone else has edited the item
+at the same time they tried to.
Web Interface
=============
-Note: this document contains screenshots of the default look and feel.
-Your site may have a slightly (or very) different look, but the
-functionality will be very similar, and the concepts still hold.
+.. note::
+ This document contains screenshots of the default look and feel.
+ Your site may have a slightly (or very) different look, but the
+ functionality will be very similar, and the concepts still hold.
The web interface is broken up into the following parts:
open (ie. not resolved) issues. This list has been generated by a bunch
of controls `under the covers`_ but for now, you can see something like:
-.. img: images/index_logged_out.png
-
-The screen is divided up into three sections:
+.. image:: images/index_logged_out.png
-.. img: images/page_layout.png
+The screen is divided up into three sections. There's a title which tells
+you where you are, a sidebar which contains useful navigation tools and a
+body which usually displays either a list of items or a single item from
+the tracker.
-you may either register or log in. Registration takes you to:
+You may either register or log in. Registration takes you to:
-.. img: images/registration.png
+.. image:: images/registration.png
-Once you're logged in, the screen changes slightly to:
+Once you're logged in, the sidebar changes to:
-.. img: images/index_logged_in.png
+.. image:: images/index_logged_in.png
-Note that the sidebar menu has changed slightly, so you can now get to
-your "My Details" page:
+You can now get to your "My Details" page:
-.. img: images/my_details.png
-
-Note the new information on this page - the history.
+.. image:: images/my_details.png
Display, edit or entry of an item
Create a new issue with "create new" under the issue subheading. This
will take you to:
-.. img: images/new_issue.png
-
-The `nosy list`_ is explained below. Enter some information and click
-"submit new entry" and you'll be rewarded with:
+.. image:: images/new_issue.png
-.. img: images/new_issue_created.png
+Editing an issue uses the same form, though now you'll see attached files
+and messages, and the issue history at the bottom of the page:
-or, if you don't enter all the required information (or some other error
-occurs) you'll get something like:
-
-.. img: images/new_issue_error.png
+.. image:: images/edit_issue.png
Searching Page
may type into the search form.
+Saving queries
+~~~~~~~~~~~~~~
+
+You may save queries in the tracker by giving the query a name. Each user
+may only have one query with a given name - if a subsequent search is
+performed with the same query name supplied, then it will edit the
+existing query of the same name.
+
+Queries may be marked as "private". These queries are only visible to the
+user that created them. If they're not marked "private" then all other
+users may include the query in their list of "Your Queries". Marking it as
+private at a later date does not affect users already using the query, nor
+does deleting the query.
+
+If a user subsequently creates or edits a public query, a new personal
+version of that query is made, with the same editing rules as described
+above.
+
Under the covers
~~~~~~~~~~~~~~~~
The searching page converts your selections into the following
arguments:
-========== =============================================================
-Argument Description
-========== =============================================================
-: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 item properties given by propname must
- have (very basic search/filter).
-========== =============================================================
+============ =============================================================
+Argument Description
+============ =============================================================
+@sort sort by prop name, optionally preceeded with '-' to give
+ descending or nothing for ascending sorting. The sort
+ argument can have several props separated with comma.
+@group group by prop name, optionally preceeded with '-' or to sort
+ in descending or nothing for ascending order. The group
+ argument can have several props separated with comma.
+@columns selects the columns that should be displayed. Default is
+ all.
+@filter indicates which properties are being used in filtering.
+ Default is none.
+propname selects the values the item properties given by propname must
+ have (very basic search/filter).
+@search_text performs a full-text search (message bodies, issue titles,
+ etc)
+============ =============================================================
You may manually write URLS that contain these arguments, like so
(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
+ keyword=security,ui&
+ @group=priority,-status&
+ @sort=-activity&
+ @filters=status,keyword&
+ @columns=title,status,fixer
Access Controls
the customisation documentation. Examples of new access controls are:
- only managers may sign off issues as complete
-- don't give users who register through email web access
+- don't give users who register through e-mail web access
- let some users edit the details of all users
E-Mail Gateway
==============
-E-mail sent to Roundup is examined for several pieces of information:
+Roundup trackers may be used to facilitate e-mail conversations around
+issues. The "nosy" list attached to each issue indicates the users who
+should receive e-mail when messages are added to the issue.
+
+When e-mail comes into a tracker that identifies an issue in the subject
+line, the content of the e-mail is attached to the issue.
+
+You may even create new issues from e-mail messages.
+
+E-mail sent to a tracker is examined for several pieces of information:
1. `subject-line information`_ identifying the purpose of the e-mail
2. `sender identification`_ using the sender of the message
3. we default the item class and try some trickiness
If the subject line contains a prefix in ``[square brackets]`` then
-we're looking at case 1 or 2 above. Note that any "re:" or "fwd:"
-prefixes are stripped off the subject line before we start looking for
-real information.
+we're looking at case 1 or 2 above. Any "re:" or "fwd:" prefixes are
+stripped off the subject line before we start looking for real
+information.
If an item designator (class name and id number, for example
``issue123``) is found there, a new "msg" item is added to the
- setting the priority of an issue::
- Subject: Re: [issue1] the coffee machine is broken! [priority=urgent]
+ Subject: Re: [issue2] the coffee machine is broken! [priority=urgent]
- adding yourself to a nosy list::
Sender identification
---------------------
-If the sender of an email is unknown to Roundup (looking up both user
-primary email addresses and their alternate addresses) then a new user
-will be created. The new user will have their username set to the "user"
-part of "user@domain" in their email address. Their password will be
+If the sender of an e-mail is unknown to Roundup (looking up both user
+primary e-mail addresses and their alternate addresses) then a new user
+may be created, depending on tracker configuration (see the `Admin
+Guide`_ section "Users and Security" for configuration details.)
+
+.. _`Admin Guide`: admin_guide.html
+
+The new user will have their username set to the "user" part of
+"user@domain" in their e-mail address. Their password will be
completely randomised, and they'll have to visit the web interface to
-have it changed. Note that some sites don't allow web access by users
-who register via email like this.
+have it changed. Some sites don't allow web access by users who register
+via e-mail like this.
E-Mail Message Content
Mail gateway script command line
--------------------------------
+Usage::
+
+ roundup-mailgw [[-C class] -S field=value]* <instance home> [method]
+
The roundup mail gateway may be called in one of three ways:
- with an instance home as the only argument,
be used. The -S or --set options uses the same
property=value[;property=value] notation accepted by the command line
roundup command or the commands that can be given on the Subject line of
-an email message.
+an e-mail message.
-It can let you set the type of the message on a per email address basis.
+It can let you set the type of the message on a per e-mail address basis.
PIPE:
In the first case, the mail gateway reads a single message from the
are both valid. The username and/or password will be prompted for if
not supplied on the command-line.
+POPS:
+ Connect to a POP server over ssl. This requires python 2.4 or later.
+ This supports the same notation as POP::
+
+ pops username:password@server
+
APOP:
Same as POP, but using Authenticated POP::
apop username:password@server
+IMAP:
+ Connect to an IMAP server. This supports the same notation as that of
+ POP mail::
+
+ imap username:password@server
+
+ It also allows you to specify a specific mailbox other than INBOX using
+ this format::
+
+ imap username:password@server mailbox
+
+IMAPS:
+ Connect to an IMAP server over ssl.
+ This supports the same notation as IMAP::
+
+ imaps username:password@server [mailbox]
+
+IMAPS_CRAM:
+ Connect to an IMAP server over ssl using CRAM-MD5 authentication.
+ This supports the same notation as IMAP::
+
+ imaps_cram username:password@server [mailbox]
Command Line Tool
=================
explained below.::
Input of... Means...
- "2000-04-17.03:45" 2000-04-17.08:45:00
+ "2000-04-17.03:45" 2000-04-17.03: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
+ "08-13.22:13" yyyy-08-13.22:13:00
+ "11-07.09:32:43" yyyy-11-07.09:32:43
+ "14:25" yyyy-mm-dd.14:25:00
+ "8:47:11" yyyy-mm-dd.08:47:11
"2003" 2003-01-01.00:00:00
"2003-04" 2003-04-01.00:00:00
"." "right now"
Using with the shell
--------------------
-With version 0.6.0 or newer of roundup which supports: multiple
-designators to display and the -d, -S and -s flags.
+With version 0.6.0 or newer of roundup (which introduced support for
+multiple designators to display and the -d, -S and -s flags):
To find all messages regarding chatting issues that contain the word
"spam", for example, you could execute the following command from the
Remember the roundup commands that accept multiple designators accept
them ',' separated so using '-dc' is almost always required.
------------------
-
-Back to `Table of Contents`_
-
-.. _`Table of Contents`: index.html
-.. _`customisation documentation`: customizing.html