Mercurial > p > roundup > code

annotate doc/user_guide.txt @ 8270:c70ffbc2a003

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
test: Override Fuzz timeout from env variable. I have a local pytest.ini where I use: env = pytest_fuzz_timeout=30000 to set a 30 second timout while keeping the default 10 second for CI because my machine is slow. So the test now looks for that env variable and uses it if set.
author John Rouillard <rouilj@ieee.org>
date Sun, 12 Jan 2025 14:14:09 -0500
parents 7d72b9a9fe9c
children 2bf0c4e7795e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6586
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6469
diff changeset
1 .. meta::
6774
e7b4ad2c57ac landmarks, skiplink, remove bad attrs, autocomplete search
John Rouillard <rouilj@ieee.org>
parents: 6613
diff changeset
2 :description:
7048
6f5054751fb6 Update meta description. Also fix test command in code.txt.
John Rouillard <rouilj@ieee.org>
parents: 6807
diff changeset
3 Describes how to interact with a tracker based on the
6f5054751fb6 Update meta description. Also fix test command in code.txt.
John Rouillard <rouilj@ieee.org>
parents: 6807
diff changeset
4 Roundup Issue Tracker. Covers web (html), and email
6f5054751fb6 Update meta description. Also fix test command in code.txt.
John Rouillard <rouilj@ieee.org>
parents: 6807
diff changeset
5 interfaces.
6586
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6469
diff changeset
6
688
b38f4f95bffd More doc tweaks
Richard Jones <richard@users.sourceforge.net>
parents: 686
diff changeset
7 ==========
659
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
8 User Guide
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9 ==========
e429649ed124 More documentation cleanups.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
11 .. contents::
4890
609edf9de0a5 docs: Remove one nesting level from ToC on subpages
anatoly techtonik <techtonik@gmail.com>
parents: 4792
diff changeset
12 :local:
686
c52122f38c9b Documentation cleanup, added info for potential (and current) developers
Richard Jones <richard@users.sourceforge.net>
parents: 659
diff changeset
13
2409
Richard Jones <richard@users.sourceforge.net>
parents: 2138
diff changeset
14 .. hint::
Richard Jones <richard@users.sourceforge.net>
parents: 2138
diff changeset
15 This document will refer to *issues* as the primary store of
Richard Jones <richard@users.sourceforge.net>
parents: 2138
diff changeset
16 information in the tracker. This is the default of the classic template,
Richard Jones <richard@users.sourceforge.net>
parents: 2138
diff changeset
17 but may vary in any given installation.
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
18
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
19
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
20 Your Tracker in a Nutshell
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
21 ==========================
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
22
8061
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
23 Your tracker holds information about issues in bundles called *items*.
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
24 An item can be an *issue* (a bug or feature request) or a *user*. The
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
25 issue-ness or user-ness is called the item's *class*. For bug
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
26 reports and features, the class is "issue", and for users the class is
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
27 "user".
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
28
8061
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
29 Each item in the tracker possesses an ID number that identifies it
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
30 alongside its item class. The combination of the class and ID number
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
31 into a label identifies a specific issue or user. For instance, user 1
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
32 (who, by the way, always serves as the "admin" user) gets referred to
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
33 as "user1". Issue number 315 gets denoted as "issue315". This label
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
34 receives the designation of the item's :term:designator.
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
35
8061
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
36 Roundup never deletes items from the database. Instead, items get
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
37 "retired". Viewing the item using its ID is still possible - thus,
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
38 "removing" an item does not disrupt references to it. A retired item
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
39 will not appear in the class listing.
1615
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
40
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
41 Accessing the Tracker
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
42 ---------------------
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
43
7278
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
44 You may access your tracker in three ways:
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
45
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
46 1. through the `web interface`_,
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
47 2. through the `e-mail gateway`_, or
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
48 3. using the `command line tool`_.
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
49
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
50 The last is usually only used by administrators. Most users will use the
3529
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
51 web and e-mail interfaces. All three are explained below.
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
52
7279
0bf616cfa178 Move mail gateway and roundup-admin doc to admin guide from user guide
John Rouillard <rouilj@ieee.org>
parents: 7278
diff changeset
53 .. _command line tool: admin_guide.html#using-roundup-admin
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
54
1615
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
55 Issue life cycles in Roundup
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
56 ----------------------------
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
57
3529
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
58 New issues may be submitted via the web or e-mail.
1615
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
59
8061
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
60 By default, the issue will have the status "unread". When the issue
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
61 receives another message, its status will change to "chatting".
1615
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
62
8061
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
63 Often, the "home" page for a tracker display all open issues (closed
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
64 issues have a status of resolved, or done-cbb (cbb - could be
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
65 better)).
1615
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
66
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
67 If an issue is closed, and a new message is received then it'll be
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
68 reopened to the state of "chatting".
1615
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
69
5827
c263187e82d1 Fix typos.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
70 The full set of **priority** and **status** values are:
3650
77e067e64035 copy over status/priority descriptions from old overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 3529
diff changeset
71
7278
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
72 .. table:: Default priorities defined for the classic template.
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
73 :name: priority table
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
74 :widths: auto
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
75
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
76 =========== =====================================
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
77 Priority Description
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
78 =========== =====================================
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
79 "critical" panic: work is stopped!
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
80 "urgent" important, but not deadly
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
81 "bug" lost work or incorrect results
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
82 "feature" want missing functionality
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
83 "wish" avoidable bugs, missing conveniences
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
84 =========== =====================================
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
85
3650
77e067e64035 copy over status/priority descriptions from old overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 3529
diff changeset
86
7278
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
87 .. table:: Default statuses defined for the classic template.
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
88 :name: status table
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
89 :widths: auto
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
90
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
91 ============= =====================================
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
92 Status Description
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
93 ============= =====================================
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
94 "unread" submitted but no action yet
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
95 "deferred" intentionally set aside
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
96 "chatting" under review or seeking clarification
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
97 "need-eg" need a reproducible example of a bug
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
98 "in-progress" understood; development in progress
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
99 "testing" we think it's done; others, please test
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
100 "done-cbb" okay for now, but could be better
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
101 "resolved" fix has been released
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
102 ============= =====================================
3650
77e067e64035 copy over status/priority descriptions from old overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 3529
diff changeset
103
8061
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
104 The tracker you are using may have different priorities and
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
105 statuses. See your tracker admin for local details.
1615
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
106
4929
57a482110a24 doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents: 4890
diff changeset
107 .. _query-tracker:
57a482110a24 doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents: 4890
diff changeset
108
1588
1ac46e7e4150 more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 1575
diff changeset
109 Entering values in your Tracker
1ac46e7e4150 more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 1575
diff changeset
110 -------------------------------
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
111
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
112 All interfaces to your tracker use the same format for entering values.
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
113 This means the web interface for entering a new issue, the web interface
3529
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
114 for searching issues, the e-mail interface and even the command-line
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
115 administration tool.
1588
1ac46e7e4150 more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 1575
diff changeset
116
8255
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
117 String Properties
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
118 ~~~~~~~~~~~~~~~~~
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
119
8061
b1d384d23cdb docs: cleanups suggested by vale.
John Rouillard <rouilj@ieee.org>
parents: 8052
diff changeset
120 These fields just take a plain text value, like ``It's broken``.
1588
1ac46e7e4150 more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 1575
diff changeset
121
8255
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
122 Number Properties
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
123 ~~~~~~~~~~~~~~~~~
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
124
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
125 These fields take a real number with decimal point like ``+12456.78``,
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
126 ``-12456.78`` ``12456.78``. It supports scientific/exponent notation
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
127 like ``3.1415E-2``. Decimal commas (e.g. ``123456,78``) or thousand
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
128 separators ``-12,456.78`` are not supported.
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
129
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
130 Integer Properties
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
131 ~~~~~~~~~~~~~~~~~~
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
132
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
133 These fields take a whole/integer number without decimal marker like
7d72b9a9fe9c docs: doc new types in user_guide; alphabetize types in reference.
John Rouillard <rouilj@ieee.org>
parents: 8253
diff changeset
134 ``123``, ``+123``, ``-123``. Exponents are not supported.
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
135
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
136 Boolean properties
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
137 ~~~~~~~~~~~~~~~~~~
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
138
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
139 These fields take a value which indicates "yes"/"no", "true"/"false",
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
140 "1"/"0" or "on"/"off".
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
141
1588
1ac46e7e4150 more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 1575
diff changeset
142
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
143 Constrained (link and multilink) properties
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
144 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
145
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3756
diff changeset
146 Fields like "Assigned To" and "Keywords" hold references to items in other
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
147 classes ("user" and "keyword" in those two cases.)
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
148
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
149 Sometimes, the selection is done through a menu, like in the "Assigned
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
150 To" field.
1588
1ac46e7e4150 more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 1575
diff changeset
151
1ac46e7e4150 more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 1575
diff changeset
152 Where the input is not a simple menu selection, we use a comma-separated
1ac46e7e4150 more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 1575
diff changeset
153 list of values to indicated which values of "user" or "keyword" are
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
154 interesting. The values may be either numeric ids or the names of items.
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
155 The special value "-1" may be used to match items where the property is
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
156 not set. For example, the following searches on the issues:
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
157
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
158 ``assignedto=richard,george``
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
159 match issues which are assigned to richard or george.
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
160 ``assignedto=-1``
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
161 match issues that are not assigned to a user.
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
162 ``assignedto=2,3,40``
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
163 match issues that are assigned to users 2, 3 or 40.
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3756
diff changeset
164 ``keyword=user interface``
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3756
diff changeset
165 match issues with the keyword "user interface" in their keyword list
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3756
diff changeset
166 ``keyword=web interface,e-mail interface``
3529
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
167 match issues with the keyword "web interface" or "e-mail interface" in
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3756
diff changeset
168 their keyword list
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3756
diff changeset
169 ``keyword=-1``
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3756
diff changeset
170 match issues with no keywords set
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
171
7971
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
172 When entering the value for a constrained property you may have a
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
173 helper (also called classhelper) available by clicking on a link
8032
ce1e65af97fb docs: fix misspelling
John Rouillard <rouilj@ieee.org>
parents: 7971
diff changeset
174 usually displayed as ``(list)``. See the section `Using the
7971
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
175 Classhelper`_ for details.
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
176
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
177 Date properties
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
178 ~~~~~~~~~~~~~~~
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
179
2750
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
180 Date-and-time stamps are specified with the date in
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
181 international standard format (``yyyy-mm-dd``) joined to the time
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
182 (``hh:mm:ss``) by a period ``.``. Dates in this form can be easily
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
183 compared and are fairly readable when printed. An example of a valid
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
184 stamp is ``2000-06-24.13:03:59``. We'll call this the "full date
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
185 format". When Timestamp objects are printed as strings, they appear in
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
186 the full date format.
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
187
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
188 For user input, some partial forms are also permitted: the whole time or
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
189 just the seconds may be omitted; and the whole date may be omitted or
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
190 just the year may be omitted. If the time is given, the time is
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
191 interpreted in the user's local time zone. The Date constructor takes
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
192 care of these conversions. In the following examples, suppose that
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
193 ``yyyy`` is the current year, ``mm`` is the current month, and ``dd`` is
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
194 the current day of the month.
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
195
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
196 - "2000-04-17" means <Date 2000-04-17.00:00:00>
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
197 - "01-25" means <Date yyyy-01-25.00:00:00>
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
198 - "2000-04-17.03:45" means <Date 2000-04-17.08:45:00>
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
199 - "08-13.22:13" means <Date yyyy-08-14.03:13:00>
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
200 - "11-07.09:32:43" means <Date yyyy-11-07.14:32:43>
4650
0485b47a39a8 issue2550766: Minor formatting issues in the docs for date properties, thanks John Kristensen.
Bernhard Reiter <bernhard@intevation.de>
parents: 4402
diff changeset
201 - "14:25" means <Date yyyy-mm-dd.19:25:00>
0485b47a39a8 issue2550766: Minor formatting issues in the docs for date properties, thanks John Kristensen.
Bernhard Reiter <bernhard@intevation.de>
parents: 4402
diff changeset
202 - "8:47:11" means <Date yyyy-mm-dd.13:47:11>
2750
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
203 - the special date "." means "right now"
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
204
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
205
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
206 When searching, a plain date entered as a search field will match that date
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
207 exactly in the database. We may also accept ranges of dates. You can
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
208 specify range of dates in one of two formats:
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
209
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
210 1. English syntax::
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
211
1599
cc96bf971b33 extended date syntax to make range searches even more useful
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1596
diff changeset
212 [From <value>][To <value>]
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
213
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
214 Keywords "From" and "To" are case insensitive. Keyword "From" is
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
215 optional.
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
216
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
217 2. "Geek" syntax::
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
218
1599
cc96bf971b33 extended date syntax to make range searches even more useful
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1596
diff changeset
219 [<value>];[<value>]
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
220
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
221 Either first or second ``<value>`` can be omitted in both syntaxes.
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
222
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
223 For example, if you enter string "from 9:00" to "Creation date" field,
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
224 roundup will find all issues, that were created today since 9 AM.
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
225
2750
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
226 The ``<value>`` may also be an interval, as described in the next section.
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
227 Searching of "-2m; -1m" on activity field gives you issues which were
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
228 active between period of time since 2 months up-till month ago.
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
229
2910
5c0e5abcb5e3 doc updates
Richard Jones <richard@users.sourceforge.net>
parents: 2750
diff changeset
230 Other possible examples (consider local time is 2003-03-08.22:07:48):
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
231
2750
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
232 - "from 2-12 to 4-2" means
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
233 <Range from 2003-02-12.00:00:00 to 2003-04-02.00:00:00>
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
234 - "FROM 18:00 TO +2m" means
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
235 <Range from 2003-03-08.18:00:00 to 2003-05-08.20:07:48>
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
236 - "12:00;" means
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
237 <Range from 2003-03-08.12:00:00 to None>
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
238 - "tO +3d" means
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
239 <Range from None to 2003-03-11.20:07:48>
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
240 - "2002-11-10; 2002-12-12" means
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
241 <Range from 2002-11-10.00:00:00 to 2002-12-12.00:00:00>
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
242 - "; 20:00 +1d" means
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
243 <Range from None to 2003-03-09.20:00:00>
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
244 - "2003" means
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
245 <Range from 2003-01-01.00:00:00 to 2003-12-31.23:59:59>
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
246 - "2003-04" means
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
247 <Range from 2003-04-01.00:00:00 to 2003-04-30.23:59:59>
7064
3359dc1dabb0 Add OAuth authentication to the mailgw script
Ralf Schlatterbeck <rsc@runtux.com>
parents: 7048
diff changeset
248
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
249
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
250 Interval properties
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
251 ~~~~~~~~~~~~~~~~~~~
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
252
2750
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
253 Date intervals are specified using the suffixes "y", "m", and "d". The
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
254 suffix "w" (for "week") means 7 days. Time intervals are specified in
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
255 hh:mm:ss format (the seconds may be omitted, but the hours and minutes
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
256 may not).
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
257
2750
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
258 - "3y" means three years
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
259 - "2y 1m" means two years and one month
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
260 - "1m 25d" means one month and 25 days
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
261 - "2w 3d" means two weeks and three days
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
262 - "1d 2:50" means one day, two hours, and 50 minutes
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
263 - "14:00" means 14 hours
a97bbd72a643 copy date/interval formatting from design spec to user guide
Richard Jones <richard@users.sourceforge.net>
parents: 2409
diff changeset
264 - "0:04:33" means four minutes and 33 seconds
1596
33a0d94c7658 searching on ranges of intervals is implemented
Andrey Lebedev <kedder@users.sourceforge.net>
parents: 1588
diff changeset
265
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
266
2138
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2136
diff changeset
267 Simple support for collision detection
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2136
diff changeset
268 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2136
diff changeset
269
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2136
diff changeset
270 Item edit pages remember when the item was last edited. When a form is
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2136
diff changeset
271 submitted, the user will be informed if someone else has edited the item
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2136
diff changeset
272 at the same time they tried to.
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2136
diff changeset
273
f76d1642014a doc cleanup, editing and creation of a What's New
Richard Jones <richard@users.sourceforge.net>
parents: 2136
diff changeset
274
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
275 Web Interface
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
276 =============
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
277
2409
Richard Jones <richard@users.sourceforge.net>
parents: 2138
diff changeset
278 .. note::
Richard Jones <richard@users.sourceforge.net>
parents: 2138
diff changeset
279 This document contains screenshots of the default look and feel.
Richard Jones <richard@users.sourceforge.net>
parents: 2138
diff changeset
280 Your site may have a slightly (or very) different look, but the
Richard Jones <richard@users.sourceforge.net>
parents: 2138
diff changeset
281 functionality will be very similar, and the concepts still hold.
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
282
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
283 The web interface is broken up into the following parts:
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
284
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
285 1. `lists of items`_,
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
286 2. `display, edit or entry of an item`_, and
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
287 3. `searching page`_.
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
288
7278
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
289 In addition to the graphical web interface, Roundup has `REST`_ and
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
290 `XMLRPC`_ interfaces. These can be used by advanced users and
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
291 programmers to automate tasks and integrate with other programs.
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
292
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
293 .. _REST: rest.html
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
294 .. _XMLRPC: xmlrpc.html
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
295
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
296 Lists of Items
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
297 --------------
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
298
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
299 The first thing you'll see when you log into Roundup will be a list of
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
300 open (ie. not resolved) issues. This list has been generated by a bunch
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
301 of controls `under the covers`_ but for now, you can see something like:
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
302
3756
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
303 .. image:: images/index_logged_out.png
7278
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
304 :width: 675
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
305 :height: 450
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
306 :alt: Image of the classic Roundup tracker showing a list of issues
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
307 that one would see before logging in.
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
308
3756
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
309 The screen is divided up into three sections. There's a title which tells
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
310 you where you are, a sidebar which contains useful navigation tools and a
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
311 body which usually displays either a list of items or a single item from
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
312 the tracker.
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
313
6257
f9c059921ccc Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents: 6174
diff changeset
314 You may register, reset your password or log in. Registration takes
f9c059921ccc Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents: 6174
diff changeset
315 you to:
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
316
3756
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
317 .. image:: images/registration.png
7278
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
318 :width: 675
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
319 :height: 450
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
320 :alt: A registration form with fields for name, login name,
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
321 password etc.
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
322
6257
f9c059921ccc Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents: 6174
diff changeset
323 Clicking on the "Lost your login?" link allows you to reset your
f9c059921ccc Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents: 6174
diff changeset
324 password. Resetting your password takes you to:
f9c059921ccc Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents: 6174
diff changeset
325
f9c059921ccc Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents: 6174
diff changeset
326 .. image:: images/reset.png
7278
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
327 :width: 605
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
328 :height: 495
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
329 :alt: A form with email address and username fields that will
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
330 trigger a password reset when submitted.
6257
f9c059921ccc Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents: 6174
diff changeset
331
f9c059921ccc Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents: 6174
diff changeset
332 You can enter your username to get a reset email sent to your primary
f9c059921ccc Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents: 6174
diff changeset
333 E-mail address. Otherwise you can enter your primary E-mail address or
f9c059921ccc Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents: 6174
diff changeset
334 an Alternate E-mail address to get a reset email sent to that address.
f9c059921ccc Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents: 6174
diff changeset
335 The reset email includes a verification link that can be used to
6807
30bb17dc9f82 add expiration of verification link
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
336 complete the password reset. The verification link expires in a week.
6257
f9c059921ccc Document password reset mechanism in web interface.
John Rouillard <rouilj@ieee.org>
parents: 6174
diff changeset
337
3756
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
338 Once you're logged in, the sidebar changes to:
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
339
3756
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
340 .. image:: images/index_logged_in.png
7278
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
341 :width: 182
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
342 :height: 399
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
343 :alt: Navigation sidebar after login showing multiple links. It now
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
344 includes a link labeled "My Details" for the user's settings.
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
345
3756
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
346 You can now get to your "My Details" page:
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
347
3756
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
348 .. image:: images/my_details.png
7278
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
349 :width: 667
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
350 :height: 558
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
351 :alt: A form allowing the user to change username, real name, email
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
352 address and it also shows activity done by the user.
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
353
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
354 Display, edit or entry of an item
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
355 ---------------------------------
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
356
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
357 Create a new issue with "create new" under the issue subheading. This
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
358 will take you to:
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
359
3756
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
360 .. image:: images/new_issue.png
7278
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
361 :width: 648
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
362 :height: 277
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
363 :alt: A form for entering a new issue with title, priority, status
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
364 and other fields. All fields are empty. It also includes an
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
365 entry box for typing free form text to describe the issue.
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
366
3756
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
367 Editing an issue uses the same form, though now you'll see attached files
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
368 and messages, and the issue history at the bottom of the page:
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
369
3756
068b3d7d4279 images for user guide
Richard Jones <richard@users.sourceforge.net>
parents: 3754
diff changeset
370 .. image:: images/edit_issue.png
7278
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
371 :width: 650
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
372 :height: 535
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
373 :alt: A form for editing an issue with title, priority, status
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
374 and other fields filled in. It also includes an entry box for
e2f257ef737f alt text for images; captions for tables; RESt/XMLRPC reference
John Rouillard <rouilj@ieee.org>
parents: 7252
diff changeset
375 typing free form text to describe the issue.
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
376
6469
98082155ffea Document "Make a copy" link
John Rouillard <rouilj@ieee.org>
parents: 6408
diff changeset
377 The "Make a copy" link duplicate the current issue copying most of the
98082155ffea Document "Make a copy" link
John Rouillard <rouilj@ieee.org>
parents: 6408
diff changeset
378 properties to a new issue. This is useful for splitting am issue into
98082155ffea Document "Make a copy" link
John Rouillard <rouilj@ieee.org>
parents: 6408
diff changeset
379 sub-issues that can be assigned to different people.
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
380
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
381 Searching Page
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
382 --------------
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
383
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
384 See `entering values in your tracker`_ for an explanation of what you
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
385 may type into the search form.
1588
1ac46e7e4150 more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 1575
diff changeset
386
1ac46e7e4150 more doc work - new improved overview doc
Richard Jones <richard@users.sourceforge.net>
parents: 1575
diff changeset
387
2136
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
388 Saving queries
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
389 ~~~~~~~~~~~~~~
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
390
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
391 You may save queries in the tracker by giving the query a name. Each user
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
392 may only have one query with a given name - if a subsequent search is
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
393 performed with the same query name supplied, then it will edit the
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
394 existing query of the same name.
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
395
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
396 Queries may be marked as "private". These queries are only visible to the
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
397 user that created them. If they're not marked "private" then all other
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
398 users may include the query in their list of "Your Queries". Marking it as
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
399 private at a later date does not affect users already using the query, nor
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
400 does deleting the query.
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
401
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
402 If a user subsequently creates or edits a public query, a new personal
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
403 version of that query is made, with the same editing rules as described
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
404 above.
ee3cf6a44f29 queries on a per-user basis, and public queries [SF#891798] :)
Richard Jones <richard@users.sourceforge.net>
parents: 2028
diff changeset
405
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
406
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
407 Under the covers
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
408 ~~~~~~~~~~~~~~~~
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
409
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
410 The searching page converts your selections into the following
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
411 arguments:
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
412
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
413 ============ =============================================================
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
414 Argument Description
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
415 ============ =============================================================
5827
c263187e82d1 Fix typos.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
416 @sort sort by prop name, optionally preceded with '-' to give
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3650
diff changeset
417 descending or nothing for ascending sorting. The sort
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3650
diff changeset
418 argument can have several props separated with comma.
5827
c263187e82d1 Fix typos.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
419 @group group by prop name, optionally preceded with '-' or to sort
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3650
diff changeset
420 in descending or nothing for ascending order. The group
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3650
diff changeset
421 argument can have several props separated with comma.
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
422 @columns selects the columns that should be displayed. Default is
7064
3359dc1dabb0 Add OAuth authentication to the mailgw script
Ralf Schlatterbeck <rsc@runtux.com>
parents: 7048
diff changeset
423 all.
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
424 @filter indicates which properties are being used in filtering.
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
425 Default is none.
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
426 propname selects the values the item properties given by propname must
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
427 have (very basic search/filter).
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
428 @search_text performs a full-text search (message bodies, issue titles,
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
429 etc)
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
430 ============ =============================================================
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
431
7406
8bc4246480bf Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7279
diff changeset
432 You may manually write URLs that contain these arguments, like so
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
433 (whitespace has been added for clarity)::
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
434
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
435 /issue?status=unread,in-progress,resolved&
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3756
diff changeset
436 keyword=security,ui&
3696
790363e96852 Sorting/grouping by multiple properties.
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3650
diff changeset
437 @group=priority,-status&
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
438 @sort=-activity&
3904
91008ec8f9a0 retire "topic" usage
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3756
diff changeset
439 @filters=status,keyword&
3036
8fa6b5747a53 updated searching / indexing docs
Richard Jones <richard@users.sourceforge.net>
parents: 2910
diff changeset
440 @columns=title,status,fixer
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
441
6592
828e2eaee7cd Document full text search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
442 Full text search using the xapian, whoosh and native indexers treats
828e2eaee7cd Document full text search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
443 the search query as a series of space separated words. Any word less
6613
2eec7a500333 Doc updates for indexers.
John Rouillard <rouilj@ieee.org>
parents: 6592
diff changeset
444 than 2 characters or more than 50 characters is discarded. Also a
6592
828e2eaee7cd Document full text search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
445 stoplist is used to remove common words like "with", "and"
828e2eaee7cd Document full text search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
446 etc. Additional stoplist words can be added in the tracker's
828e2eaee7cd Document full text search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
447 config.ini file. Once filtering of the word list is done, each indexed
828e2eaee7cd Document full text search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
448 item (e.g. title, file or message content ...) is searched and if all
828e2eaee7cd Document full text search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
449 the terms are found in the item the item is returned. Then the items
828e2eaee7cd Document full text search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
450 are mapped to an issue and the list of matching issues is generated.
828e2eaee7cd Document full text search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
451
828e2eaee7cd Document full text search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
452 Other searching backends such as native-fts can be used in which case
828e2eaee7cd Document full text search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
453 the filtering above is not used. The search query can support
828e2eaee7cd Document full text search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
454 structure such as quoted phrases, matching one term or another rather
828e2eaee7cd Document full text search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
455 than both (or search), prefixes etc. In this case you should look at
6613
2eec7a500333 Doc updates for indexers.
John Rouillard <rouilj@ieee.org>
parents: 6592
diff changeset
456 the `documentation for configuring the native-fts`_ backend to find
2eec7a500333 Doc updates for indexers.
John Rouillard <rouilj@ieee.org>
parents: 6592
diff changeset
457 the supported format and features.
2eec7a500333 Doc updates for indexers.
John Rouillard <rouilj@ieee.org>
parents: 6592
diff changeset
458
2eec7a500333 Doc updates for indexers.
John Rouillard <rouilj@ieee.org>
parents: 6592
diff changeset
459 .. _`documentation for configuring the native-fts`: admin_guide.html#configuring-native-fts-full-text-search
1575
f5d53a939b67 more doc
Richard Jones <richard@users.sourceforge.net>
parents: 1570
diff changeset
460
8171
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
461 Advanced Searching with Property Expressions
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
462 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
463
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
464 You can create more advanced searches in your tracker by using Reverse
8173
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
465 Polish Notation (`RPN`_) to make property expressions. By default,
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
466 when filtering by multiple items, the expression type is 'or'. For
8171
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
467 instance, if you filter the property assignedto by adding the query
8173
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
468 string element ``assignedto=2,3,40``, it matches users numbered ``2 or
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
469 3 or 40``. In RPN, this would be written as ``2, 3, or, 4,
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
470 or``. Roundup uses negative numbers to represent operators. For
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
471 example, using "-1" for a single value (e.g. the assignedto Link
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
472 property, but not the keyword multivalued/MultiLink property) matches
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
473 an issue where the property is 'not set'.
8171
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
474
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
475 The operators and their corresponding numbers are:
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
476
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
477 * 'not' is represented by -2
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
478 * 'and' is represented by -3
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
479 * 'or' is represented by -4
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
480
8173
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
481 So, ``assignedto=2,3,40`` is the same as
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
482 ``assignedto=2,3,-4,40,-4``. While this example is the same as
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
483 ``2,3,40``, the expression ``keyword=1,2,-3,-2`` filters issues that
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
484 don't have both keywords 1 and 2.
8171
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
485
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
486 Another example is: ``creator=3,-2,1,-2,-3``. This is the same as the
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
487 expression: ``(not user3) and (not user1)``. Using the rules of logic,
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
488 this is the same as: ``not (user3 or user1)`` which is expressed in
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
489 RPN as ``creator=3,1,-4,-2``. Compare this to ``creator=3,1,-2`` which
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
490 returns issues created by user3 or any user other than user1.
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
491
8173
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
492 Another example, useful when filtering issues, is::
8172
6a58acc3f39f docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8171
diff changeset
493
6a58acc3f39f docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8171
diff changeset
494 keyword=-1,-2,1,8,-3,-2,-3
6a58acc3f39f docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8171
diff changeset
495
6a58acc3f39f docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8171
diff changeset
496 which returns issues that have one or more keywords set and the issue
6a58acc3f39f docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8171
diff changeset
497 does not have keyword1 and keyword8 both set. In more standard infix
8173
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
498 form::
8172
6a58acc3f39f docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8171
diff changeset
499
6a58acc3f39f docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8171
diff changeset
500 not empty and not (keyword1 and keyword8)
6a58acc3f39f docs: new example, summary issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8171
diff changeset
501
8173
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
502 Typing these expressions manually can be tiresome and tricky. On the
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
503 search page, there's an expression editor. You can access it by
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
504 clicking on the ``(expr)`` link, which makes creating these
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
505 expressions a bit easier.
079958914ed7 doc/test: issue2551374 - add error handling for filter expressions
John Rouillard <rouilj@ieee.org>
parents: 8172
diff changeset
506
8253
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
507 If your expression has an error, you will be returned to the search
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
508 page and an error will be reported. For example using the expression
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
509 ``1, -3`` to search the nosy property of an issue generates the
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
510 following error::
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
511
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
512 There was an error searching issue by nosy using: [1, -3]. The
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
513 operator -3 (and) at position 2 has too few arguments.
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
514
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
515 The error message gives you the problem element (``-3``), it's meaning
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
516 (``and``) and its position: the second element. The problem was caused
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
517 because ``and`` requires two arguments, but only one argument (``1``)
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
518 was given.
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
519
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
520 Another error message::
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
521
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
522 There was an error searching issue by status using: [1, 2, -3,
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
523 -3]. The operator -3 (and) at position 4 has too few arguments.
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
524
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
525 reports that the second ``-3`` in the 4th position is the problem
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
526 operator. Note that this search expression will never return any
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
527 values. This is because ``status`` is a single value (link) type
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
528 property. It can't have the values ``1`` and ``2``, so the expression
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
529 ``1,2,-3`` will never return an issue.
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
530
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
531 In the examples above, the error was caused by not having enough
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
532 arguments. However you can also have too many arguments. An example of
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
533 this type of message is::
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
534
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
535 There was an error searching issue by nosy using: [4, 5, 1, 2, -3,
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
536 -3]. There are too many arguments for the existing operators. The
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
537 values on the stack are: [Value 4, (Value 5 AND (Value 1 AND Value
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
538 2))]
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
539
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
540 This message gives you the expression as far as it was able to compose
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
541 it, but value 1 is not combined with the rest of the expression. So
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
542 another binary operator is needed to complete the expression.
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
543
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
544 If you have multiple incorrect expressions in your search, only one
cae1bbf2536b fix: issue2551374 - Add error handling for filter expressions. Fix UI
John Rouillard <rouilj@ieee.org>
parents: 8173
diff changeset
545 expression will be reported each time you submit the search.
8171
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
546
7971
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
547 Using the Classhelper
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
548 ---------------------
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
549
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
550 The classhelper makes finding the id number or name for linked items
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
551 easier. It is usually invoked from the parent window by clicking on
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
552 the ``(list)`` link. There are two classhelpers: classic and
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
553 component. This documentation discusses the newer component
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
554 classhelper available with Roundup 2.4.0 or newer. If there is a
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
555 problem with the component classhelper, it reports the problem and
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
556 falls back to using the classic classhelper.
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
557
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
558 The component classhelper is displayed in a popup window. You can
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
559 interact with the original window by moving the popup out of the way
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
560 or minimizing it. If you don't see a popup, check to see if your
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
561 browser has disabled popup windows.
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
562
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
563 The classhelper has three parts:
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
564
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
565 1. an optional search pane
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
566 2. a selection pane
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
567 3. an accumulator pane
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
568
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
569 .. image:: images/classhelper-issue-all.png
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
570 :width: 675
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
571 :height: 914
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
572 :alt: Image of the new component classhelper popup. The image shows
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
573 the operating system window decorations with a title of "Superseder
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
574 Classhelper - issue2". Then it shows a search panel with options to
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
575 enter text to search issue titles or status and a select/dropdown
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
576 to search by a keyword on the issue. Below the options are search
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
577 and reset buttons. Below the search panel is a selection
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
578 panel that shows buttons to move to the previous or next pages and
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
579 says that it is displaying items 26 to 50. This is followed by a
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
580 scrollable table of issues where each row has a checkbox and the
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
581 box for issue 114 is checked. At the bottom of the window is a text
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
582 box that lists a number of issue numbers including 114. To the
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
583 right of the text box are apply and cancel buttons.
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
584
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
585
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
586 The search pane has text or select/dropdown fields to search for a
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
587 matching item. The image above shows a search for issues. The Title
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
588 and Status properties can be matched using a text input while the
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
589 Keyword property can be selected from a dropdown. Hitting enter while
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
590 in a text input will trigger a search and the results will be
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
591 displayed below the search pane in the selection pane. Tabbing to the
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
592 search button and pressing enter will also trigger a search. The reset
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
593 button will clear the search form.
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
594
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
595 Below the search pane is the select pane. It lists the number of items
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
596 displayed (26-50) and includes two buttons to move to the previous or
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
597 next page of search results. If there is no search pane, this will
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
598 display a page of items from all the items in the class. Below the
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
599 pagination component is the scrollable selection table. Each row in
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
600 the table has a checkbox and one or more columns of data about the
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
601 item. Clicking on a row toggles the item's checkbox and adds or
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
602 removes the id or name for the item in the accumulator's
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
603 display. Arrow keys or tab/shift-tab can be used to scroll through
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
604 each item in the selection table. The space key or enter will
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
605 select/deselect the item. You can jump to the page controls using the
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
606 '<' and '>' keys. Once the page control button is focused, press enter
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
607 to trigger a page change.
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
608
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
609 The bottom pane consists of a text input called the accumulator
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
610 display. It lists all the items that have been selected. The first two
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
611 items in this example were selected from the previous selection
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
612 page. Next to the display are the apply and cancel buttons. You can
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
613 jump to the apply button quickly by pressing Shift-Enter as long as
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
614 you are not in a search input. Once the apply button is focused, press
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
615 enter to copy the items in the display to the associated field on the
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
616 parent window. If you activate the cancel button or close the window
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
617 using the window decoration, the classhelper will close and not change
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
618 the parent window.
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
619
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
620 The classhelper can also be used in read-only mode. In this mode, the
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
621 accumulator is not shown. Also the checkboxes are not displayed. To
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
622 close the classhelper in read-only mode use the window decoration or a
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
623 hotkey (e.g. control-w).
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
624
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
625 You can have multiple classhelpers up at a time. The title on the
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
626 window identifies the property and item the classhelper will
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
627 modify. For example the image shows the superseder for issue2.
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
628
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
629 Do not refresh the classhelper window using the ``F5`` key. This will
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
630 erase the contents of the window and you will have to close it and
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
631 invoke the link from the parent window again.
fe0348bbe45b issue2551353 - Add roundup-classhelper for 2.4.0 release
John Rouillard <rouilj@ieee.org>
parents: 7406
diff changeset
632
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
633 Access Controls
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
634 ---------------
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
635
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
636 User access is controlled through Permissions. These are are grouped
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
637 into Roles, and users have a comma-separated list of Roles assigned to
7406
8bc4246480bf Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7279
diff changeset
638 them. Roles can allow you to access:
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
639
7406
8bc4246480bf Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7279
diff changeset
640 - an entire class of items (e.g. issues)
8bc4246480bf Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7279
diff changeset
641 - only certain fields of a class (e.g. you can see the username but
8bc4246480bf Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7279
diff changeset
642 not the phone number of other users)
8bc4246480bf Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7279
diff changeset
643 - fields or classes based on your relationship to an item (e.g.
8bc4246480bf Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7279
diff changeset
644 you can see the phone number of your user entry since you are the
8bc4246480bf Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7279
diff changeset
645 owner of your user entry)
8bc4246480bf Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7279
diff changeset
646
8bc4246480bf Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7279
diff changeset
647 Other permissions divide access controls up into answering questions
8bc4246480bf Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7279
diff changeset
648 like:
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
649
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
650 - may the user edit issues ("Edit", "issue")
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
651 - is the user allowed to use the web interface ("Web Access")
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
652 - may the user edit other user's Roles through the web ("Web Roles")
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
653
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
654 Any number of new Permissions and Roles may be created as described in
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
655 the customisation documentation. Examples of new access controls are:
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
656
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
657 - only managers may sign off issues as complete
3529
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
658 - don't give users who register through e-mail web access
1317
28ae91aae74f clarifications
Richard Jones <richard@users.sourceforge.net>
parents: 1282
diff changeset
659 - let some users edit the details of all users
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
660
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
661 E-Mail Gateway
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
662 ==============
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
663
3529
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
664 Roundup trackers may be used to facilitate e-mail conversations around
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
665 issues. The "nosy" list attached to each issue indicates the users who
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
666 should receive e-mail when messages are added to the issue.
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
667
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
668 When e-mail comes into a tracker that identifies an issue in the subject
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
669 line, the content of the e-mail is attached to the issue.
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
670
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
671 You may even create new issues from e-mail messages.
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
672
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
673 E-mail sent to a tracker is examined for several pieces of information:
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
674
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
675 1. `subject-line information`_ identifying the purpose of the e-mail
1615
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
676 2. `sender identification`_ using the sender of the message
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
677 3. `e-mail message content`_ which is to be extracted
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
678 4. e-mail attachments which should be associated with the message
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
679
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
680
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
681 Subject-line information
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
682 ------------------------
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
683
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
684 The subject line of the incoming message is examined to find one of:
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
685
5827
c263187e82d1 Fix typos.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
686 1. a case insensitive ``help``,
5056
d995ee7d49bf issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents: 5045
diff changeset
687 2. a match for ``-- key <OneTimeKey>``,
d995ee7d49bf issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents: 5045
diff changeset
688 3. the item that the message is responding to,
d995ee7d49bf issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents: 5045
diff changeset
689 4. the type of item the message should create, or
d995ee7d49bf issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents: 5045
diff changeset
690 5. we default the item class and try some trickiness.
d995ee7d49bf issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents: 5045
diff changeset
691
d995ee7d49bf issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents: 5045
diff changeset
692 If the subject is ``help`` (case insensitive), the gateway responds
5827
c263187e82d1 Fix typos.
John Rouillard <rouilj@ieee.org>
parents: 5610
diff changeset
693 with an explanation of the interface.
5056
d995ee7d49bf issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents: 5045
diff changeset
694
d995ee7d49bf issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents: 5045
diff changeset
695 If a one-time key is found, we're processing an in-progress
d995ee7d49bf issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents: 5045
diff changeset
696 registration confirmation.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
697
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
698 If the subject line contains a prefix in ``[square brackets]`` then
7234
86862ed039fa issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents: 7093
diff changeset
699 we're looking at case 3 or 4 above. Spaces are allowed inside the
86862ed039fa issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents: 7093
diff changeset
700 brackets and after the class item name. So ``[issue2]`` and
7252
9c067ed4568b add pragma command to roundup-admin
John Rouillard <rouilj@ieee.org>
parents: 7234
diff changeset
701 ``[ issue 2 ]`` are treated the same where any white space is optional.
7234
86862ed039fa issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents: 7093
diff changeset
702 Any "re:" or "fwd:" prefixes are stripped off the subject line before
86862ed039fa issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents: 7093
diff changeset
703 we start looking for real information.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
704
7406
8bc4246480bf Link designator terms to glossary; expand permission doc; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 7279
diff changeset
705 If an item :term:`designator` (class name and id number, for example
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
706 ``issue123``) is found there, a new "msg" item is added to the
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
707 "messages" property for that item, and any new "file" items are added to
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
708 the "files" property for the item.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
709
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
710 If just an item class name is found there, we attempt to create a new
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
711 item of that class with its "messages" property initialized to contain
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
712 the new "msg" item and its "files" property initialized to contain any
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
713 new "file" items.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
714
5056
d995ee7d49bf issue2550757: one bug raised by issue fixed. Patch created by
John Rouillard <rouilj@ieee.org>
parents: 5045
diff changeset
715 The fifth case above - where no ``[information]`` is provided, the
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
716 tracker's ``MAIL_DEFAULT_CLASS`` configuration variable defines what
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
717 class of item the message relates to. We try to match the subject line
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
718 to an existing item of the default class, and if there's a match, the
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
719 message is related to that matched item. If not, then a new item of the
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
720 default class is created.
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
721
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
722
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
723 Setting Properties
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
724 ~~~~~~~~~~~~~~~~~~
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
725
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
726 The e-mail interface also provides a simple way to set properties on
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
727 items. At the end of the subject line, propname=value pairs can be
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
728 specified in square brackets, using the same conventions as for the
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
729 roundup set shell command.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
730
8052
d54af8964fe3 docs: fix unwanted highlighting.
John Rouillard <rouilj@ieee.org>
parents: 8032
diff changeset
731 .. highlight:: text
d54af8964fe3 docs: fix unwanted highlighting.
John Rouillard <rouilj@ieee.org>
parents: 8032
diff changeset
732
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
733 For example,
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
734
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
735 - setting the priority of an issue::
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
736
4298
f6468c5e1493 Fix typo in email section of user guide, fixes issue2550607
Richard Jones <richard@users.sourceforge.net>
parents: 4036
diff changeset
737 Subject: Re: [issue2] the coffee machine is broken! [priority=urgent]
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
738
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
739 - adding yourself to a nosy list::
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
740
7234
86862ed039fa issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents: 7093
diff changeset
741 Subject: Re: [ issue2 ] we're out of widgets [nosy=+richard]
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
742
1282
2feb3e0a9955 included doc ideas from Bernhard Reiter
Richard Jones <richard@users.sourceforge.net>
parents: 1267
diff changeset
743 - setting the nosy list to just you and cliff::
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
744
7234
86862ed039fa issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents: 7093
diff changeset
745 Subject: Re: [issue 2] we're out of widgets [nosy=richard,cliff]
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
746
1282
2feb3e0a9955 included doc ideas from Bernhard Reiter
Richard Jones <richard@users.sourceforge.net>
parents: 1267
diff changeset
747 - removing yourself from a nosy list and setting the priority::
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
748
7234
86862ed039fa issue2551262 - make mail gateway subject prefix parsing accept spaces
John Rouillard <rouilj@ieee.org>
parents: 7093
diff changeset
749 Subject: Re: [ issue 2 ] we're out of widgets [nosy=-richard;priority=bug]
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
750
8052
d54af8964fe3 docs: fix unwanted highlighting.
John Rouillard <rouilj@ieee.org>
parents: 8032
diff changeset
751 .. highlight:: python3
d54af8964fe3 docs: fix unwanted highlighting.
John Rouillard <rouilj@ieee.org>
parents: 8032
diff changeset
752
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
753 In all cases, the message relates to issue 2. The ``Re:`` prefix is
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
754 stripped off.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
755
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
756
1267
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
757 Automatic Properties
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
758 ~~~~~~~~~~~~~~~~~~~~
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
759
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
760 **status of new issues**
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
761 When a new message is received that is not identified as being related
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
762 to an existing issue, it creates a new issue. The status of the new
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
763 issue is defaulted to "unread".
1267
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
764
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
765 **reopening of resolved issues**
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
766 When a message is is received for a resolved issue, the issue status is
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
767 automatically reset to "chatting" to indicate new information has been
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
768 received.
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
769
a28dfdb6c9a5 doc refinement
Richard Jones <richard@users.sourceforge.net>
parents: 1228
diff changeset
770
1615
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
771 Sender identification
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
772 ---------------------
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
773
3529
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
774 If the sender of an e-mail is unknown to Roundup (looking up both user
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
775 primary e-mail addresses and their alternate addresses) then a new user
4018
17bdd79a3ae1 clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents: 3904
diff changeset
776 may be created, depending on tracker configuration (see the `Admin
17bdd79a3ae1 clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents: 3904
diff changeset
777 Guide`_ section "Users and Security" for configuration details.)
17bdd79a3ae1 clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents: 3904
diff changeset
778
17bdd79a3ae1 clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents: 3904
diff changeset
779 .. _`Admin Guide`: admin_guide.html
17bdd79a3ae1 clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents: 3904
diff changeset
780
17bdd79a3ae1 clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents: 3904
diff changeset
781 The new user will have their username set to the "user" part of
17bdd79a3ae1 clarify default permission change
Richard Jones <richard@users.sourceforge.net>
parents: 3904
diff changeset
782 "user@domain" in their e-mail address. Their password will be
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
783 completely randomised, and they'll have to visit the web interface to
2409
Richard Jones <richard@users.sourceforge.net>
parents: 2138
diff changeset
784 have it changed. Some sites don't allow web access by users who register
3529
4fd84dcfed33 more explanation
Richard Jones <richard@users.sourceforge.net>
parents: 3036
diff changeset
785 via e-mail like this.
1615
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
786
7b680b906417 more user docco
Richard Jones <richard@users.sourceforge.net>
parents: 1599
diff changeset
787
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
788 E-Mail Message Content
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
789 ----------------------
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
790
6408
ef7bc1fac35a Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents: 6257
diff changeset
791 By default Roundup only associates plain text (MIME type
ef7bc1fac35a Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents: 6257
diff changeset
792 ``text/plain``) as messages for items. Any other parts of a message
ef7bc1fac35a Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents: 6257
diff changeset
793 are associated as downloadable files. If no plain text part is found,
ef7bc1fac35a Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents: 6257
diff changeset
794 the message is rejected. The tracker can be configured to enable
ef7bc1fac35a Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents: 6257
diff changeset
795 ``convert_htmltotext``. If this is enabled, an email with an HTML
ef7bc1fac35a Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents: 6257
diff changeset
796 message (MIME type ``text/html``) and no ``text/plain`` part will be
ef7bc1fac35a Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents: 6257
diff changeset
797 accepted. The first HTML part will be converted to text and used as
ef7bc1fac35a Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents: 6257
diff changeset
798 the message for the item. Subsequent parts will be treated as
ef7bc1fac35a Update user_guide to include support for html messages.
John Rouillard <rouilj@ieee.org>
parents: 6257
diff changeset
799 attachments.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
800
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
801 To do this, incoming messages are examined for multiple parts:
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
802
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
803 * In a multipart/mixed message or part, each subpart is extracted and
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
804 examined. The text/plain subparts are assembled to form the textual
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
805 body of the message, to be stored in the file associated with a "msg"
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
806 class item. Any parts of other types are each stored in separate files
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
807 and given "file" class items that are linked to the "msg" item.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
808 * In a multipart/alternative message or part, we look for a text/plain
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
809 subpart and ignore the other parts.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
810
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
811 If the message is a response to a previous message, and contains quoted
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
812 sections, then these will be stripped out of the message if the
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
813 ``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
814
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
815 Message summary
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
816 ~~~~~~~~~~~~~~~
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
817
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
818 The "summary" property on message items is taken from the first
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
819 non-quoting section in the message body. The message body is divided
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
820 into sections by blank lines. Sections where the second and all
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
821 subsequent lines begin with a ">" or "|" character are considered
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
822 "quoting sections". The first line of the first non-quoting section
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
823 becomes the summary of the message.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
824
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
825
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
826 Address handling
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
827 ----------------
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
828
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
829 All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
830 message are looked up among the tracker users, and the corresponding
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
831 users are placed in the "recipients" property on the new "msg" item. The
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
832 address in the ``From:`` header similarly determines the "author"
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
833 property of the new "msg" item. The default handling for addresses that
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
834 don't have corresponding users is to create new users with no passwords
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
835 and a username equal to the address.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
836
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
837 The addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
838 the message may be added to the `nosy list`_ depending on:
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
839
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
840 ``ADD_AUTHOR_TO_NOSY``
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
841 Does the author of a message get placed on the nosy list automatically?
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
842 If 'new' is used, then the author will only be added when a message
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
843 creates a new issue. If 'yes', then the author will be added on
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
844 followups too. If 'no', they're never added to the nosy.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
845
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
846 ``ADD_RECIPIENTS_TO_NOSY``
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
847 Do the recipients (To:, Cc:) of a message get placed on the nosy list?
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
848 If 'new' is used, then the recipients will only be added when a message
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
849 creates a new issue. If 'yes', then the recipients will be added on
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
850 followups too. If 'no', they're never added to the nosy.
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
851
5045
a46d5d0fd5f8 Fix issue1615201: Added a new configuration option EMAIL_KEEP_REAL_FROM
Peter Funk <pf@artcom-gmbh.de>
parents: 4929
diff changeset
852 Some organisations might prefer to have someone moderate emails before
7064
3359dc1dabb0 Add OAuth authentication to the mailgw script
Ralf Schlatterbeck <rsc@runtux.com>
parents: 7048
diff changeset
853 they are delivered into Roundup. Those might want to set the
5045
a46d5d0fd5f8 Fix issue1615201: Added a new configuration option EMAIL_KEEP_REAL_FROM
Peter Funk <pf@artcom-gmbh.de>
parents: 4929
diff changeset
854 configuration option ``EMAIL_KEEP_REAL_FROM`` to ``'yes'`` to avoid
a46d5d0fd5f8 Fix issue1615201: Added a new configuration option EMAIL_KEEP_REAL_FROM
Peter Funk <pf@artcom-gmbh.de>
parents: 4929
diff changeset
855 having the moderators address appearing as the creator of issues.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
856
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
857 Nosy List
1199
cd58a8603424 half-backed cleaning up of user guide
Richard Jones <richard@users.sourceforge.net>
parents: 1098
diff changeset
858 ~~~~~~~~~
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
859
1228
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
860 Roundup watches for additions to the "messages" property of items.
Richard Jones <richard@users.sourceforge.net>
parents: 1199
diff changeset
861
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
862 When a new message is added, it is sent to all the users on the "nosy"
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
863 list for the item that are not already on the "recipients" list of the
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
864 message. Those users are then appended to the "recipients" property on
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
865 the message, so multiple copies of a message are never sent to the same
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
866 user. The journal recorded by the hyperdatabase on the "recipients"
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
867 property then provides a log of when the message was sent to whom.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
868
1661
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
869 If the author of the message is also in the nosy list for the item that
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
870 the message is attached to, then the config var ``MESSAGES_TO_AUTHOR``
b9c1226cb600 Reflowed text to 72 cols...
Jean Jordaan <neaj@users.sourceforge.net>
parents: 1615
diff changeset
871 is queried to determine if they get a nosy list copy of the message too.
881
85cc6e6a94b8 better mailgw user docs
Richard Jones <richard@users.sourceforge.net>
parents: 753
diff changeset
872
8171
188b7a549f20 docs: issue2550698 - Document the logical expression search a bit
John Rouillard <rouilj@ieee.org>
parents: 8061
diff changeset
873 .. _`RPN`: https://en.wikipedia.org/wiki/Reverse_Polish_notation
Roundup Issue Tracker: http://roundup-tracker.org/