Mercurial > ~dholland > hg > swallowtail > index.cgi
annotate doc/swallowtail.tex @ 37:edf081d0b282
Need to retain the mime-type of messages.
author | David A. Holland |
---|---|
date | Sun, 15 Jun 2014 17:13:50 -0400 |
parents | d18135398d0f |
children | 45bb7b516edb |
rev | line source |
---|---|
15
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
1 %\documentclass[11pt,twocolumn]{article} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
2 \documentclass[11pt]{article} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
3 \usepackage{fullpage} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
4 |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
5 \usepackage{graphicx} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
6 \usepackage{url} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
7 \usepackage{parskip} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
8 |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
9 \usepackage{charter} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
10 \usepackage{courier} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
11 \frenchspacing |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
12 |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
13 % without help, latex sets these characters in the wrong font inside \tt |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
14 % (I thought this was mostly fixed, but it's still happening in some cases) |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
15 \newcommand{\us}{{\tt\char`\_}} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
16 \newcommand{\bra}{{\tt\char`\{}} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
17 \newcommand{\ket}{{\tt\char`\}}} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
18 \newcommand{\bs}{{\tt\char`\\}} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
19 \newcommand{\caret}{{\tt\char`\^}} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
20 |
18 | 21 % The search strings ``XXX'' and ``future'' are intentionally |
22 % supported in the text below. | |
23 | |
15
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
24 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
25 |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
26 \title{The Swallowtail Bugtracking System} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
27 \author{David A. Holland} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
28 \date{September 3, 2012} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
29 |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
30 \begin{document} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
31 \maketitle |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
32 |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
33 \section{Introduction} |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
34 |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
35 Swallowtail is a bugtracking system meant to serve as a migration path |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
36 for large GNATS installations. |
18 | 37 It is intended to address various shortcomings of GNATS that appear |
38 with a large database, and to provide a migration path for that | |
39 database that does not lose information. | |
40 | |
41 As in GNATS, individual bug reports are called PRs (``problem | |
42 reports'') and are given unique numbers from an increasing sequence. | |
43 | |
44 The database is kept in PostgreSQL. | |
45 | |
46 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
47 \section{Design Criteria} | |
48 | |
49 Swallowtail is intended for use by large projects that take their bug | |
50 tracking seriously. | |
51 It assumes the existence of a project server that can host the | |
52 database, and that project developers have shell access on this | |
53 machine. | |
54 Unless special measures are taken, everyone with shell access to the | |
55 host machine is assumed to be a developer and has developer-level | |
56 access to the database. | |
57 Developers are assumed to be grownups, at least mentally, and to not | |
58 require either baby-sitting or padded cells. | |
59 Developers are also assumed to be generally clueful and able to take | |
60 advantage of direct query access to the database. | |
61 | |
62 A web interface is also provided but it allows only end-user-level | |
63 access. | |
64 It also does not attempt to offer the full range of query and | |
65 annotation support. | |
35 | 66 (At least to begin with.) |
18 | 67 |
68 It is assumed that most bug report traffic will be handled by email, | |
69 and that all public traffic will be reflected onto one or more mailing | |
70 lists for general distribution. | |
71 However, both new bug reports and followup traffic can be submitted | |
72 via the web interface. | |
73 It is not necessary to sign up to file a bug report. | |
74 | |
75 Swallowtail assumes that the database is large (as bug databases go, | |
76 not large in DBMS terms), both in terms of the total number of bugs on | |
77 file and the number of issues currently open. | |
78 This means that hand-editing is not feasible. | |
79 Manual generation of semantic indexes and tags is presumed possible | |
80 but expensive. | |
81 It is assumed that multiple types of semantic indexing and tagging | |
82 will be required. | |
83 Supporting this is the primary motivation for creating Swallowtail at | |
84 all. | |
85 | |
86 Swallowtail is also intended to replace GNATS, so it explicitly allows | |
87 importing an existing GNATS database without losing information. | |
88 (One of the major problems with migrating away from GNATS, or | |
89 migrating any bug database, is that most bug databases have a | |
90 hardcoded schema with fixed semantics, and no two are equivalent.) | |
91 | |
92 It also is written to allow incoming bug reports to be sent with the | |
93 GNATS send-pr tool, as this tool is deployed in the field and can be | |
94 updated in the field only gradually. | |
95 | |
96 We are explicitly assuming that everything that talks directly to | |
97 GNATS can be updated, rewritten, or replaced for Swallowtail, and | |
98 that there are relatively few such things. | |
99 | |
100 Swallowtail is being written specifically to manage NetBSD's bug | |
101 database, but it is intended to remain general enough to be useful to | |
102 other groups who may be in a similar position. | |
103 | |
104 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
105 \section{Submitting PRs} | |
106 | |
107 New PRs can be submitted either by email or via a web form. | |
108 The email interface accepts only structured mail in the form sent by | |
109 the GNATS send-pr tool. | |
110 Malformed emails are returned. | |
111 (Sending handwritten mail to the PR submission address is not | |
112 supported.) | |
113 | |
114 The web form requires a valid email address, as most transactions are | |
115 handled by email. | |
116 In the future it might be desirable to set up a scheme that allows | |
117 entirely web-based access for end users. | |
118 | |
119 XXX: need to decide whether/how much to validate email addresses in | |
120 the web form, and also what measures to take to prevent spam. | |
121 Maybe an email address already in the system can be used to submit new | |
122 PRs without any kind of further validation step. | |
123 | |
124 XXX: Also I wonder if we ought to have a blacklist for emails that | |
125 aren't allowed to submit PRs. | |
126 | |
127 Submitting a PR generates an email to the submitter that reports the | |
128 PR number and includes brief instructions for further actions. | |
129 If the PR is confidential, a notice to this effect is included in the | |
130 response mail, as well as instructions and/or a link for making the PR | |
131 non-confidential. | |
132 (This is because most confidential PR submissions are confidential by | |
133 mistake.) | |
134 The mail also includes a generated password for logging in to the web | |
135 interface as a submitter. | |
136 (Currently this does nothing; in the future it will allow e.g. | |
137 unsubscribing from the PR.) | |
138 | |
139 The submitter of a PR is automatically subscribed to the PR as a | |
140 respondent. | |
141 | |
142 Note that currently Swallowtail does not provide its own send-pr | |
143 script, as this is not required for the initial deployment. | |
144 There will probably be one in the future. | |
145 | |
146 NetBSD: The submission address for NetBSD will be | |
147 swallowtail@NetBSD.org (unless we decide on something else) although | |
148 the old gnats-bugs address will be kept for the indefinite future to | |
149 allow old send-pr scripts to continue to work. | |
150 | |
151 GNATS: For some reason GNATS accepts a wide range of malformed | |
152 incoming emails. | |
153 This almost invariably makes a mess when it occurs. | |
154 | |
155 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
156 \section{Retrieving PRs} | |
157 | |
158 The web interface includes a scheme for retrieving any PR | |
159 (except PRs marked confidential) by a well-known address. | |
160 The search page also allows retrieving a single PR by number. | |
161 | |
162 NetBSD: The address will probably be \url{http://bugs.netbsd.org/12345}. | |
163 | |
164 In the web interface, text within the administrative or message logs | |
165 that can be identified as a PR number is rendered as a clickable link. | |
166 | |
167 Email addresses are not displayed in the web interface at all. | |
168 (Or maybe, in the future when this is possible, only when logged in.) | |
169 | |
170 The \texttt{query-pr} command line tool can retrieve any PR, including | |
171 confidential PRs. | |
172 This is done by passing it the PR number. | |
173 As in GNATS the option \texttt{--full} prints the message and | |
174 administrative logs as well as the base PR data. | |
175 Use \texttt{--attach N} to retrieve an attachment. | |
176 | |
177 \texttt{query-pr} can also be used for searching. | |
178 See below. | |
179 | |
180 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
181 \section{Commenting on PRs} | |
182 | |
183 Comments on PRs can be submitted either by email or via the PR's web | |
184 page. | |
185 In either case, files can be provided (as MIME attachments or via | |
186 upload) that are filed as attachments to the PR. | |
187 Comments on PRs can also be submitted by running \texttt{comment-pr}, | |
188 or from \texttt{browse-pr}. | |
189 All comments go to the PR's message log. | |
190 | |
191 MIME multipart messages that include both text and HTML will be | |
192 converted to plain text. | |
193 MIME mail that is HTML-only will be rejected. | |
194 The MIME content-type of mails is retained, so if non-ASCII mail | |
195 appears it can be displayed correctly, and so remailed text is marked | |
196 correctly. | |
197 | |
198 The comment address is the same as the submission address. | |
199 Comments are identified by the Subject: line, which should begin with | |
200 \texttt{Re: category/12345} like in GNATS. | |
201 (In the future we might switch to a tidier tagging scheme, such as | |
202 \texttt{[NetBSD 12345]} anywhere in the Subject: line, but the old | |
203 style will have to be supported indefinitely regardless.) | |
204 The category need not be the right category for the PR; if it is | |
205 wrong, the right one will be substituted before the comment is filed | |
206 or remailed. | |
207 Also, if the Subject: line of a comment is empty except for the tag, | |
208 the PR's synopsis will be inserted. | |
209 | |
210 Source control commit messages routed to the bug database are treated | |
211 as comments. | |
212 | |
213 Comments are remailed to all email addresses subscribed to the PR, | |
214 and also (if not confidential) to the mailing list associated with the | |
215 PR's category. | |
216 | |
217 Remailed comments have a References: header that allows them to thread | |
218 together. | |
219 (The contents of it need to be site-configurable.) | |
220 | |
221 Comments filed on a locked PR go to the administrator queue. | |
222 | |
223 GNATS: GNATS has no web-based way of filing comments, which | |
224 occasionally annoys people. | |
225 | |
226 GNATS: GNATS has no MIME support at all and corrupts mails with | |
227 attachments when filing them in the database (not fatally but | |
228 annoyingly), which aggravates everyone regularly. | |
229 | |
230 GNATS: GNATS cannot lock PRs, and old PRs often receive spam or | |
231 misdirected mail that has to be cleaned up by hand. | |
232 | |
233 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
234 \section{Updating/Editing PRs} | |
235 | |
236 PRs are edited with \texttt{edit-pr}. | |
237 (This is not accessible to end users. | |
238 An end user wanting to adjust the PR state should file a comment | |
239 requesting the change.) | |
240 | |
241 Changes made with \texttt{edit-pr} are recorded in the PR's | |
242 administrative log. | |
243 (XXX: some of them should be mailed out and not others, but it isn't | |
244 clear which are which yet.) | |
245 | |
246 Each PR has the following base properties: | |
247 \begin{itemize} | |
248 | |
249 \item | |
250 Its number. | |
251 (This cannot be changed.) | |
252 | |
253 \item | |
254 The \emph{synopsis}. | |
255 This is a short (one-line) description of the PR provided by the | |
256 submitter. | |
257 It can (and should) be adjusted as necessary during the lifetime of | |
258 the PR. | |
259 | |
260 If in a new submission or conversion from GNATS the Subject: line of | |
261 the email is not the same as the synopsis field, the effect will be | |
262 that the synopsis is first set to the provided Subject: and then to | |
263 the provided synopsis, generating the corresponding change entry in | |
264 the PR's administrative log. | |
265 | |
266 \item | |
267 The confidential flag. | |
268 PRs marked confidential can be accessed only by developers, and | |
269 traffic about them is not reflected to mailing lists. | |
270 | |
271 \item | |
272 The \emph{state}. | |
273 This is the basic state the PR is in. | |
274 (Open, closed, pending-pullups, etc.) | |
275 The list of states is configurable. | |
276 States have a name (which should be an identifier), a description, and | |
277 flags that identify if the state is a closed state, whether reminder | |
278 and/or feedback mail should be sent. | |
279 There is also an obsolete flag that prevents new uses of the state. | |
280 | |
281 NetBSD: we will start out with the same set of states as we have in | |
282 GNATS, plus ``stuck''. | |
283 (A PR is stuck if a respondent is needed and there are none.) | |
284 | |
285 XXX: when you put a PR into feedback state you should provide a | |
286 timeout period and whether the PR should, if the timeout expires, be | |
287 changed to ``stuck'' or ``closed''. | |
288 | |
289 \item | |
290 The \emph{locked} flag. | |
291 A locked PR cannot be edited or commented on until it is first | |
292 unlocked. | |
293 Attempting to run \texttt{edit-pr} or \texttt{comment-pr} on a locked | |
294 PR will result in a message that the PR is locked and the option to | |
295 unlock it or abort. | |
296 (Filing a comment on a locked PR by email or via the web interface | |
297 results in the comment going to the administrator queue.) | |
298 PRs are automatically locked by the system a month after being | |
299 closed. | |
300 | |
301 The database conversion from GNATS will mark all PRs locked that have | |
302 been closed for more than a month. | |
303 | |
304 GNATS: GNATS does not support locked PRs. | |
305 | |
306 \item | |
307 The database schema version that was current when the PR arrived. | |
308 This is useful for knowing what conversions were applied to the | |
309 data. | |
310 The initial schema version is 1. | |
311 Version 0 means ``converted from GNATS''. | |
312 | |
313 \item | |
314 The date (and time) that the PR arrived. | |
315 | |
316 \item | |
317 The date (and time) that the PR was closed, if appropriate. | |
318 | |
319 \item | |
320 The original submitter, who remains the original submitter even if | |
321 later unsubscribed. | |
322 | |
323 \item | |
324 The \emph{release}, which is the Release field from GNATS. | |
325 | |
326 \item | |
327 The \emph{environment}, which is the Environment field from GNATS. | |
328 | |
329 \item | |
330 The administrative log, which is a list of messages generated when the | |
331 PR is updated. | |
332 | |
333 \item | |
334 The message log, which is a list of comments filed on the PR and their | |
335 attachments. | |
336 | |
337 \item | |
338 The subscription lists. | |
339 As described below, a user can be subscribed in any of three ways | |
340 (and more than once). | |
341 Each subscription also has a ``batch'' flag to send out update mails | |
342 in bundles. | |
343 (XXX: it is not clear if this needs to be implemented up front or not.) | |
344 | |
345 \item | |
346 Classification entries. | |
347 There are, in general, multiple classification schemes, which come in | |
348 different flavors. | |
349 Each PR has a value for each classification scheme (which might be | |
350 missing or null in some cases) whose allowable values and meaning are | |
351 defined by the classification scheme. | |
352 The GNATS Severity, Priority, Class, and Category fields are handled | |
353 as classification schemes. | |
354 (The category scheme has some special-case handling as described | |
355 elsewhere.) | |
356 | |
357 \end{itemize} | |
358 | |
359 The mail from-address and message-ID, which are retained by GNATS, are | |
360 in Swallowtail just handled as entries in the administrative log. | |
361 | |
362 The Description, How-To-Repeat, and Fix fields of a GNATS PR, along | |
363 with any ``unformatted'' text that confused GNATS, are in Swallowtail | |
364 handled as the initial entries in the PR's message log. | |
365 | |
366 Idea for the future: provide up/down vote buttons (both in the web | |
367 page and in edit-pr) to help rank the importance of individual bugs. | |
368 If you are also seeing a particular problem, you vote it up; if you | |
369 are using the affected software but not seeing it, you vote it | |
370 down. | |
371 Or something like that. | |
372 | |
373 The data associated with users is described in another section below. | |
374 Decoupling user data from individual PRs makes it feasible to update | |
375 your email address in the database, which is tedious to the point of | |
376 impossible with GNATS. | |
377 | |
378 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
379 \section{Tracking PRs} | |
380 | |
381 The simple way to track PRs is to subscribe to the mailing list(s) | |
382 that Swallowtail traffic is reflected to. | |
383 However, since those lists are likely to be high volume, and also do | |
384 not carry traffic about confidential PRs, it is also possible to | |
385 subscribe directly to individual PRs. | |
386 | |
387 In the web interface, there is a link for this. | |
388 XXX: there should be a way to do this by email, but it isn't yet clear | |
389 what it should be. | |
390 | |
391 Everyone subscribed to a PR receives a copy of all comments made on | |
392 the PR, and notices of significant administrative changes. | |
393 There are two additional modes: | |
394 | |
395 \begin{itemize} | |
396 | |
397 \item | |
398 A \emph{respondent} is someone who is experiencing the problem and can | |
399 provide feedback if needed. | |
400 The original submitter is always subscribed as a respondent, but | |
401 especially for old PRs, they may disapper and others may appear. | |
402 | |
403 \item | |
404 A \emph{responsible party} is someone who is fixing the problem, or at | |
405 least taking charge of seeing that it gets fixed. | |
406 This may be a specific developer, or it may be a role account that | |
407 looks after PRs nobody specific is handling. | |
408 For new PRs a default responsible party can be subscribed based on the | |
409 PR category. | |
410 Ordinarily only one developer will be subscribed as responsible. | |
411 | |
412 \end{itemize} | |
413 | |
414 If the last respondent with \texttt{mailto} permission unsubscribes | |
415 (or is unsubscribed) from a PR that is in feedback state, it is | |
416 automatically switched to the stuck state. | |
417 (XXX: but do we want to make ``stuck'' a known special case like this?) | |
418 | |
419 XXX: there should be a way to bring a PR to the attention of another | |
420 developer short of subscribing them to it. | |
421 | |
422 In the future there should be an RSS feed for each PR, but this is not | |
423 expected to be implemented in the first rollout. | |
424 (There should also be individual RSS feeds for categories, and based | |
425 on classification schemes, and whatever else.) | |
426 | |
427 GNATS: GNATS has no ability to allow anyone but the original submitter | |
428 to function as a respondent. | |
429 | |
430 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
431 \section{Reminder Mails} | |
432 | |
433 The system periodically sends out two kinds of mail: \emph{reminder | |
434 mail}, that goes to developers responsible for open PRs, and | |
435 \emph{feedback mail}, that goes to the submitters (typically) of PRs | |
436 that have been placed in feedback state. | |
437 | |
438 One reminder mail is sent to each developer subscribed as | |
439 ``responsible'' to at least one PR, listing the PR by number and | |
440 synopsis. | |
441 (XXX: sorted how?) | |
442 Reminders are not sent for PRs that are in feedback. | |
443 | |
444 NetBSD: reminders are also not sent for PRs that are in | |
445 pending-pullups state. | |
446 | |
447 Feedback mail is sent to each user subscribed as ``respondent'' to at | |
448 least one PR. | |
449 If the user is being nagged about three or fewer PRs, one email is | |
450 sent for each PR, with the headers adjusted so replies get filed in | |
451 that PR. | |
452 This makes it easier for casual users to respond correctly. | |
453 If the user is being nagged about more PRs than that, only one mail is | |
454 sent, in the same form as reminder mail. | |
455 In the future the feedback mails will repeat the message requesting | |
456 feedback; this is not expected to be implemented for the initial | |
457 deployment. | |
458 | |
459 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
460 \section{Statistical Reporting} | |
461 | |
462 Various scripts to gather statistics are provided, both as part of the | |
463 web interface and to generate periodic report mail. | |
464 | |
465 These include: | |
466 \begin{itemize} | |
467 | |
468 \item The summary statistics, originally written by Erik E. Fair for | |
469 the NetBSD GNATS; | |
470 | |
471 \item A daily report, based on the one GNATS sends to the netbsd-bugs | |
472 mailing list; | |
473 | |
474 \item A monthly report, based on the one I wrote to send to the | |
475 developers list; | |
476 | |
477 \item Whatever other stuff may come up or looks interesting. | |
478 | |
479 \end{itemize} | |
480 | |
481 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
482 \section{Searching for PRs} | |
483 | |
484 The web interface provides a simple search form, which can search on | |
485 various fields or on text in the log. | |
486 In the future this may be made more powerful; for the time being it is | |
487 expected to remain largely the same as the interface to GNATS. | |
488 | |
489 Command-line searching can be done with \texttt{query-pr}. | |
490 Any value in any field can be matched; text search in the | |
491 administrative and message logs (or anywhere in the PR) is also | |
492 supported. | |
493 XXX: this should take advantage of postgres's full text search tools, | |
494 and this section should be rewritten once it's clear what that | |
495 provides. | |
496 | |
497 There is a flag for also searching closed PRs, which are skipped by | |
498 default. | |
499 There is also a flag to retrieve a randomly selected PR. | |
500 | |
501 Note that the weird GNATS query-pr query language is not supported. | |
502 (Complex queries are best issued using the SQL interface.) | |
15
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
503 |
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
504 |
18 | 505 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
506 \section{Browsing the Database} | |
507 | |
508 The tool \texttt{browse-pr} is provided for examining the database. | |
35 | 509 Its user interface is reminiscent of a newsreader, e.g. slrn. |
18 | 510 And, it will probably only be implemented in the future. |
35 | 511 (It is something I would really like to have, but it's not critical |
512 for the first deployment.) | |
18 | 513 |
514 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
515 \section{Direct SQL Interface} | |
516 | |
517 XXX: document this, including particularly the views that developers | |
518 are meant to use to look at things. | |
519 | |
520 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
521 \section{Database Users} | |
522 | |
523 Unlike GNATS, the Swallowtail database tracks users explicitly. | |
524 Each one has a username and a real name, and one or more email | |
525 addresses. | |
526 When more than one email address is on file, one of the addresses is | |
527 selected for sending mail. | |
528 The Organization field that GNATS stores and send-pr provides is filed | |
529 with the email address that sent it. | |
530 The database also tracks the last time mail was received from each | |
531 address, as this is often useful when sorting out problems. | |
532 | |
533 Each address also has a ``web password'' attached to it. | |
534 This is generated randomly when the address is first encountered | |
535 in a PR submission and sent back to the user in the response to the | |
536 submission. | |
537 In the future it is meant to allow logging into the web site as a | |
538 submitter; for now it does nothing. | |
539 | |
540 Each user also has the following permission bits: | |
541 \begin{itemize} | |
542 | |
543 \item | |
544 \texttt{mailto} -- if this is false, Swallowtail will not send any | |
545 email to this user. | |
546 If the only users subscribed to a PR as respondents have mail | |
547 disabled (or there are no users subscribed as respondents) setting the | |
548 PR to feedback state will fail. | |
549 This flag can be used for users whose mail bounces, or who are | |
550 otherwise no longer available. | |
551 | |
552 \item | |
553 \texttt{responsible} -- if this is true, the user is allowed to be | |
554 responsible for open PRs. | |
555 This should normally be set for all developers, and only developers, | |
556 and should be cleared when a developer quits. | |
557 (Any open PRs they are responsible for should be reassigned.) | |
558 It should also be set for role accounts that are responsible by | |
559 default when nobody else is. | |
560 | |
561 \item | |
562 \texttt{oldresponsible} -- if this is true, the user is allowed to be | |
563 responsible only for closed PRs. | |
564 This should be set if \texttt{responsible} is set, and should also be | |
565 left set when a developer quits. | |
566 | |
567 \item | |
568 \texttt{editpr} -- if this is true, the user is allowed to run | |
569 \texttt{edit-pr} and make changes to the database. | |
570 This should be set for all developers, and only developers, and should | |
571 be cleared when a developer quits. | |
572 | |
573 \item | |
574 \texttt{admin} -- if this is true, the user is allowed to perform | |
575 administrative tasks. | |
576 | |
577 \end{itemize} | |
578 | |
579 Note that while all developers are assumed to have a username, end | |
580 users will in general not have one. | |
581 | |
582 XXX: what's the mechanism for updating user information? | |
583 | |
584 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
585 \section{Administrator Queue} | |
586 | |
587 The database contains an explicit queue, or in fact several explicit | |
588 queues, of issues requiring administrator attention. | |
589 The following subsections describe the components of the administrator | |
590 queue. | |
591 The administrator queue is accessible only to users with the | |
592 \texttt{admin} permission bit set. | |
593 | |
594 \subsection{Comments filed on locked PRs.} | |
595 | |
596 When a comment is made on a PR that is locked, instead of being | |
597 applied to the PR it is placed in the administrator queue for manual | |
598 attention. | |
599 The possible actions are: | |
600 \begin{itemize} | |
601 \item defer: put it off for tomorrow; | |
602 \item accept: add it to the PR, for valid/intended comments; | |
603 \item new: create a new PR instead; | |
604 \item reroute: send to another PR instead, for mistyped PR numbers; | |
605 \item bounce: return to sender, for non-spam with no clear other choice; | |
606 \item discard: erase it, as comments on locked PRs are often spam. | |
607 \end{itemize} | |
608 | |
609 Accepting a comment on a locked PR automatically unlocks it, and by | |
610 default also reopens it. | |
611 | |
612 \subsection{Feedback mail bounces.} | |
613 | |
614 When bounced mail arrives, Swallowtail examines it to try to determine | |
615 which PR and which user it applies to. | |
616 If it appears to be a bounce generated from feedback mail (or from | |
617 reminder mail) it goes into this queue. | |
618 The full mail is retained for inspection. | |
619 | |
620 The possible actions are: | |
621 \begin{itemize} | |
622 \item defer: put it off for tomorrow; | |
623 \item count: just add one to the number of bounces recorded; | |
624 \item changeaddr: change to a different address for the same user; | |
625 \item nomail: inhibit sending further mail to the user; | |
626 \item discard: delete the mail from the queue. | |
627 \end{itemize} | |
628 % XXX the count used by ``count'' needs to be described in the user | |
629 % data section. | |
630 | |
631 \subsection{Other mail bounces.} | |
632 | |
633 Bounced mail that can be associated with a PR and/or user but is not | |
634 feedback goes into this queue. | |
635 The actions are the same as for feedback bounces. | |
636 | |
637 \subsection{Junk mail.} | |
638 | |
639 All other unrecognized mail goes into this queue. | |
640 The possible actions are: | |
641 \begin{itemize} | |
642 \item defer: put it off for tomorrow; | |
643 \item forward: forward it somewhere (normally to yourself); | |
644 \item discard: erase it. | |
645 \end{itemize} | |
646 | |
647 (XXX: maybe this stuff should just be forwarded on or dumped out into | |
648 a mailbox somewhere.) | |
649 | |
650 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
651 \section{Classification Schemes} | |
652 | |
653 Here is a quick discussion of the classification schemes that we | |
654 expect to use, or might use. | |
655 | |
19
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
656 There are four kinds of classifications: enumerated (the value must be |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
657 one from a fixed set of constants), tags (the value is zero or more |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
658 constants from a fixed pool), text (the value can be any string), and |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
659 hierarchical (like enumerated, but with structure). |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
660 |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
661 In the long run some of the things that are currently PR states may |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
662 want to be tags instead. |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
663 |
18 | 664 \subsection{Enumerated classifications} |
665 | |
666 \paragraph{Category.} | |
667 The part of the system affected, in broad terms. | |
668 The same as the GNATS ``Category'' field. | |
669 This classification is special-cased in some places, at least for now; | |
670 in the future it might make sense to allow those places to do matching | |
671 on arbitrary classifications. | |
672 | |
673 \paragraph{Class.} | |
674 The GNATS ``Class'' field: \texttt{sw-bug}, \texttt{doc-bug}, | |
675 \texttt{change-request}, etc. | |
676 | |
677 \paragraph{Severity.} | |
678 The GNATS ``Severity'' field. | |
679 | |
680 \paragraph{Priority.} | |
681 | |
682 The GNATS ``Priority'' field. | |
683 | |
19
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
684 \subsection{Tag sets.} |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
685 |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
686 \paragraph{Release-goals.} |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
687 Tags like \texttt{6-CRITICAL}, to be applied and managed by releng |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
688 when planning for a release. |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
689 |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
690 \paragraph{Branch-notes.} |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
691 Tags like \texttt{5-ONLY}, to mark bugs that do not affect HEAD and |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
692 that can therefore be retired along with branches. |
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
693 |
18 | 694 \subsection{Text classifications} |
695 | |
696 \paragraph{Manpage.} | |
697 The name of the nearest man page to where the problem appears to be. | |
698 FreeBSD has been using this as a tagging scheme for some time. | |
699 | |
700 \paragraph{Package.} | |
21 | 701 The identity (category/directory form) of the package affected. |
18 | 702 (For pkgsrc bugs only.) |
703 | |
704 \subsection{Hierarchical taxonomies} | |
705 | |
706 \paragraph{Subsystem.} | |
707 The hierarchical taxonomy I've been using for the buglists web page. | |
708 | |
709 \paragraph{Consequences.} | |
710 A hierarchical taxonomy of the results of the problem (annoyance, | |
711 system crash, remote root exploit, etc.) | |
712 | |
713 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
714 \section{Other Future Features} | |
715 | |
716 Some other things that aren't likely to be deployed immediately but | |
717 are worth considering later: | |
718 | |
719 \begin{itemize} | |
720 | |
721 \item Have a way to note dependencies among PRs, as in 12345 is | |
722 stalled until 24680 is fixed. | |
723 (This does not occur often enough in practice to be a priority.) | |
724 | |
725 \item Have a way to massedit a group of PRs; for example, put all PRs | |
726 against a particular driver or filesystem or whatever into feedback | |
727 after major fixes. | |
728 | |
729 \item There should be administrator buttons for moving comments to | |
730 different PRs, for e.g. misfiled comment notices. | |
731 | |
732 \item It should be possible for users to set personal tags/priorities | |
733 for annotating and/or sorting nag mail. | |
734 (E.g. sort by priority, or age, or time since last change, etc.) | |
735 | |
20
675b7dd62bba
I just thought of another thing for the future list.
David A. Holland
parents:
19
diff
changeset
|
736 \item It would be good for each nag mail (at least reminder mail, |
675b7dd62bba
I just thought of another thing for the future list.
David A. Holland
parents:
19
diff
changeset
|
737 maybe not feedback mail) to report the changes in the list since the |
675b7dd62bba
I just thought of another thing for the future list.
David A. Holland
parents:
19
diff
changeset
|
738 last one that went out. |
675b7dd62bba
I just thought of another thing for the future list.
David A. Holland
parents:
19
diff
changeset
|
739 |
18 | 740 \item It should be possible to blacklist Cc: of certain addresses |
741 (particularly internal lists) in bug traffic. | |
742 | |
743 \item Any new send-pr script should be configurable by the user with | |
744 return addresses and default values for organization and so forth. | |
745 | |
746 \item It would be nice to be able to track PR status separately (or | |
747 semi-separately) for release branches. | |
748 However, it isn't clear how to do this without making a cumbersome | |
749 mess. | |
750 | |
751 \item It might be useful to be able to explicitly merge duplicate PRs, | |
752 without either losing information or creating a confused mess of | |
753 interleaved comments. | |
754 | |
755 \item It might be worth adding threading for comments. | |
756 | |
757 \item We should figure out how to make Google see and index the pages | |
758 for each PR. | |
759 Or maybe just the open ones. | |
760 | |
761 \item It would be nice if the web page for each PR had browse features | |
762 like links for ``show all PRs of this priority'' or ``show all PRs | |
763 from this submitter'' and whatnot. | |
764 | |
765 \item Lists of PRs in the web interface should have a sidebar to let | |
766 you narrow the list, and a list of the filters currently applied (like | |
767 e.g. NewEgg's product searches). | |
768 Also, the sort order should be defined (unlike GNATS) and selectable. | |
769 | |
770 \item It might be worthwhile to allow PR subscriptions in a brief mode | |
771 where all you get is ``Joe commented on PR 12345''. | |
772 | |
773 \item We will eventually want a way to turn MIME blobs already in the | |
774 database into attachments. | |
775 | |
776 \item Should have per-user tags that are more or less private. | |
777 | |
778 \item Should have per-user tags that are public. | |
779 | |
35 | 780 \item In the long run it should be possible to log into the web |
781 interface as a developer and do all developer things there instead of | |
782 from the command line. | |
783 | |
18 | 784 |
785 \end{itemize} | |
786 | |
787 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
15
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
788 \end{document} |