Mercurial > ~dholland > hg > swallowtail > index.cgi
annotate doc/swallowtail.tex @ 35:d18135398d0f
Some clarifications.
(in particular, clarify that full access via the web interface is a
long-term goal, just not an immediate priority)
Regenerating the pdf file will have to wait for PR 48884.
| author | David A. Holland |
|---|---|
| date | Sun, 08 Jun 2014 19:15:48 -0400 |
| parents | ecae2581f825 |
| 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} |