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