Mercurial > ~dholland > hg > swallowtail > index.cgi
annotate doc/swallowtail.tex @ 39:45bb7b516edb
document previous better
| author | David A. Holland |
|---|---|
| date | Sun, 15 Jun 2014 17:28:02 -0400 |
| parents | d18135398d0f |
| children |
| 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 | |
| 39 | 281 States can be tagged for timeout support; when a PR is put into a |
| 282 state tagged for timeout (e.g. ``feedback'') you give a time and a | |
| 283 reversion state, and if nothing happens in the meantime the state is | |
| 284 automatically changed at the given time. | |
| 285 | |
| 18 | 286 NetBSD: we will start out with the same set of states as we have in |
| 287 GNATS, plus ``stuck''. | |
| 288 (A PR is stuck if a respondent is needed and there are none.) | |
| 289 | |
| 290 \item | |
| 291 The \emph{locked} flag. | |
| 292 A locked PR cannot be edited or commented on until it is first | |
| 293 unlocked. | |
| 294 Attempting to run \texttt{edit-pr} or \texttt{comment-pr} on a locked | |
| 295 PR will result in a message that the PR is locked and the option to | |
| 296 unlock it or abort. | |
| 297 (Filing a comment on a locked PR by email or via the web interface | |
| 298 results in the comment going to the administrator queue.) | |
| 299 PRs are automatically locked by the system a month after being | |
| 300 closed. | |
| 301 | |
| 302 The database conversion from GNATS will mark all PRs locked that have | |
| 303 been closed for more than a month. | |
| 304 | |
| 305 GNATS: GNATS does not support locked PRs. | |
| 306 | |
| 307 \item | |
| 308 The database schema version that was current when the PR arrived. | |
| 309 This is useful for knowing what conversions were applied to the | |
| 310 data. | |
| 311 The initial schema version is 1. | |
| 312 Version 0 means ``converted from GNATS''. | |
| 313 | |
| 314 \item | |
| 315 The date (and time) that the PR arrived. | |
| 316 | |
| 317 \item | |
| 318 The date (and time) that the PR was closed, if appropriate. | |
| 319 | |
| 320 \item | |
| 321 The original submitter, who remains the original submitter even if | |
| 322 later unsubscribed. | |
| 323 | |
| 324 \item | |
| 325 The \emph{release}, which is the Release field from GNATS. | |
| 326 | |
| 327 \item | |
| 328 The \emph{environment}, which is the Environment field from GNATS. | |
| 329 | |
| 330 \item | |
| 331 The administrative log, which is a list of messages generated when the | |
| 332 PR is updated. | |
| 333 | |
| 334 \item | |
| 335 The message log, which is a list of comments filed on the PR and their | |
| 336 attachments. | |
| 337 | |
| 338 \item | |
| 339 The subscription lists. | |
| 340 As described below, a user can be subscribed in any of three ways | |
| 341 (and more than once). | |
| 342 Each subscription also has a ``batch'' flag to send out update mails | |
| 343 in bundles. | |
| 344 (XXX: it is not clear if this needs to be implemented up front or not.) | |
| 345 | |
| 346 \item | |
| 347 Classification entries. | |
| 348 There are, in general, multiple classification schemes, which come in | |
| 349 different flavors. | |
| 350 Each PR has a value for each classification scheme (which might be | |
| 351 missing or null in some cases) whose allowable values and meaning are | |
| 352 defined by the classification scheme. | |
| 353 The GNATS Severity, Priority, Class, and Category fields are handled | |
| 354 as classification schemes. | |
| 355 (The category scheme has some special-case handling as described | |
| 356 elsewhere.) | |
| 357 | |
| 358 \end{itemize} | |
| 359 | |
| 360 The mail from-address and message-ID, which are retained by GNATS, are | |
| 361 in Swallowtail just handled as entries in the administrative log. | |
| 362 | |
| 363 The Description, How-To-Repeat, and Fix fields of a GNATS PR, along | |
| 364 with any ``unformatted'' text that confused GNATS, are in Swallowtail | |
| 365 handled as the initial entries in the PR's message log. | |
| 366 | |
| 367 Idea for the future: provide up/down vote buttons (both in the web | |
| 368 page and in edit-pr) to help rank the importance of individual bugs. | |
| 369 If you are also seeing a particular problem, you vote it up; if you | |
| 370 are using the affected software but not seeing it, you vote it | |
| 371 down. | |
| 372 Or something like that. | |
| 373 | |
| 374 The data associated with users is described in another section below. | |
| 375 Decoupling user data from individual PRs makes it feasible to update | |
| 376 your email address in the database, which is tedious to the point of | |
| 377 impossible with GNATS. | |
| 378 | |
| 379 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
| 380 \section{Tracking PRs} | |
| 381 | |
| 382 The simple way to track PRs is to subscribe to the mailing list(s) | |
| 383 that Swallowtail traffic is reflected to. | |
| 384 However, since those lists are likely to be high volume, and also do | |
| 385 not carry traffic about confidential PRs, it is also possible to | |
| 386 subscribe directly to individual PRs. | |
| 387 | |
| 388 In the web interface, there is a link for this. | |
| 389 XXX: there should be a way to do this by email, but it isn't yet clear | |
| 390 what it should be. | |
| 391 | |
| 392 Everyone subscribed to a PR receives a copy of all comments made on | |
| 393 the PR, and notices of significant administrative changes. | |
| 394 There are two additional modes: | |
| 395 | |
| 396 \begin{itemize} | |
| 397 | |
| 398 \item | |
| 399 A \emph{respondent} is someone who is experiencing the problem and can | |
| 400 provide feedback if needed. | |
| 401 The original submitter is always subscribed as a respondent, but | |
| 402 especially for old PRs, they may disapper and others may appear. | |
| 403 | |
| 404 \item | |
| 405 A \emph{responsible party} is someone who is fixing the problem, or at | |
| 406 least taking charge of seeing that it gets fixed. | |
| 407 This may be a specific developer, or it may be a role account that | |
| 408 looks after PRs nobody specific is handling. | |
| 409 For new PRs a default responsible party can be subscribed based on the | |
| 410 PR category. | |
| 411 Ordinarily only one developer will be subscribed as responsible. | |
| 412 | |
| 413 \end{itemize} | |
| 414 | |
| 415 If the last respondent with \texttt{mailto} permission unsubscribes | |
| 416 (or is unsubscribed) from a PR that is in feedback state, it is | |
| 417 automatically switched to the stuck state. | |
| 418 (XXX: but do we want to make ``stuck'' a known special case like this?) | |
| 419 | |
| 420 XXX: there should be a way to bring a PR to the attention of another | |
| 421 developer short of subscribing them to it. | |
| 422 | |
| 423 In the future there should be an RSS feed for each PR, but this is not | |
| 424 expected to be implemented in the first rollout. | |
| 425 (There should also be individual RSS feeds for categories, and based | |
| 426 on classification schemes, and whatever else.) | |
| 427 | |
| 428 GNATS: GNATS has no ability to allow anyone but the original submitter | |
| 429 to function as a respondent. | |
| 430 | |
| 431 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
| 432 \section{Reminder Mails} | |
| 433 | |
| 434 The system periodically sends out two kinds of mail: \emph{reminder | |
| 435 mail}, that goes to developers responsible for open PRs, and | |
| 436 \emph{feedback mail}, that goes to the submitters (typically) of PRs | |
| 437 that have been placed in feedback state. | |
| 438 | |
| 439 One reminder mail is sent to each developer subscribed as | |
| 440 ``responsible'' to at least one PR, listing the PR by number and | |
| 441 synopsis. | |
| 442 (XXX: sorted how?) | |
| 443 Reminders are not sent for PRs that are in feedback. | |
| 444 | |
| 445 NetBSD: reminders are also not sent for PRs that are in | |
| 446 pending-pullups state. | |
| 447 | |
| 448 Feedback mail is sent to each user subscribed as ``respondent'' to at | |
| 449 least one PR. | |
| 450 If the user is being nagged about three or fewer PRs, one email is | |
| 451 sent for each PR, with the headers adjusted so replies get filed in | |
| 452 that PR. | |
| 453 This makes it easier for casual users to respond correctly. | |
| 454 If the user is being nagged about more PRs than that, only one mail is | |
| 455 sent, in the same form as reminder mail. | |
| 456 In the future the feedback mails will repeat the message requesting | |
| 457 feedback; this is not expected to be implemented for the initial | |
| 458 deployment. | |
| 459 | |
| 460 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
| 461 \section{Statistical Reporting} | |
| 462 | |
| 463 Various scripts to gather statistics are provided, both as part of the | |
| 464 web interface and to generate periodic report mail. | |
| 465 | |
| 466 These include: | |
| 467 \begin{itemize} | |
| 468 | |
| 469 \item The summary statistics, originally written by Erik E. Fair for | |
| 470 the NetBSD GNATS; | |
| 471 | |
| 472 \item A daily report, based on the one GNATS sends to the netbsd-bugs | |
| 473 mailing list; | |
| 474 | |
| 475 \item A monthly report, based on the one I wrote to send to the | |
| 476 developers list; | |
| 477 | |
| 478 \item Whatever other stuff may come up or looks interesting. | |
| 479 | |
| 480 \end{itemize} | |
| 481 | |
| 482 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
| 483 \section{Searching for PRs} | |
| 484 | |
| 485 The web interface provides a simple search form, which can search on | |
| 486 various fields or on text in the log. | |
| 487 In the future this may be made more powerful; for the time being it is | |
| 488 expected to remain largely the same as the interface to GNATS. | |
| 489 | |
| 490 Command-line searching can be done with \texttt{query-pr}. | |
| 491 Any value in any field can be matched; text search in the | |
| 492 administrative and message logs (or anywhere in the PR) is also | |
| 493 supported. | |
| 494 XXX: this should take advantage of postgres's full text search tools, | |
| 495 and this section should be rewritten once it's clear what that | |
| 496 provides. | |
| 497 | |
| 498 There is a flag for also searching closed PRs, which are skipped by | |
| 499 default. | |
| 500 There is also a flag to retrieve a randomly selected PR. | |
| 501 | |
| 502 Note that the weird GNATS query-pr query language is not supported. | |
| 503 (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
|
504 |
|
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
505 |
| 18 | 506 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
| 507 \section{Browsing the Database} | |
| 508 | |
| 509 The tool \texttt{browse-pr} is provided for examining the database. | |
| 35 | 510 Its user interface is reminiscent of a newsreader, e.g. slrn. |
| 18 | 511 And, it will probably only be implemented in the future. |
| 35 | 512 (It is something I would really like to have, but it's not critical |
| 513 for the first deployment.) | |
| 18 | 514 |
| 515 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
| 516 \section{Direct SQL Interface} | |
| 517 | |
| 518 XXX: document this, including particularly the views that developers | |
| 519 are meant to use to look at things. | |
| 520 | |
| 521 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
| 522 \section{Database Users} | |
| 523 | |
| 524 Unlike GNATS, the Swallowtail database tracks users explicitly. | |
| 525 Each one has a username and a real name, and one or more email | |
| 526 addresses. | |
| 527 When more than one email address is on file, one of the addresses is | |
| 528 selected for sending mail. | |
| 529 The Organization field that GNATS stores and send-pr provides is filed | |
| 530 with the email address that sent it. | |
| 531 The database also tracks the last time mail was received from each | |
| 532 address, as this is often useful when sorting out problems. | |
| 533 | |
| 534 Each address also has a ``web password'' attached to it. | |
| 535 This is generated randomly when the address is first encountered | |
| 536 in a PR submission and sent back to the user in the response to the | |
| 537 submission. | |
| 538 In the future it is meant to allow logging into the web site as a | |
| 539 submitter; for now it does nothing. | |
| 540 | |
| 541 Each user also has the following permission bits: | |
| 542 \begin{itemize} | |
| 543 | |
| 544 \item | |
| 545 \texttt{mailto} -- if this is false, Swallowtail will not send any | |
| 546 email to this user. | |
| 547 If the only users subscribed to a PR as respondents have mail | |
| 548 disabled (or there are no users subscribed as respondents) setting the | |
| 549 PR to feedback state will fail. | |
| 550 This flag can be used for users whose mail bounces, or who are | |
| 551 otherwise no longer available. | |
| 552 | |
| 553 \item | |
| 554 \texttt{responsible} -- if this is true, the user is allowed to be | |
| 555 responsible for open PRs. | |
| 556 This should normally be set for all developers, and only developers, | |
| 557 and should be cleared when a developer quits. | |
| 558 (Any open PRs they are responsible for should be reassigned.) | |
| 559 It should also be set for role accounts that are responsible by | |
| 560 default when nobody else is. | |
| 561 | |
| 562 \item | |
| 563 \texttt{oldresponsible} -- if this is true, the user is allowed to be | |
| 564 responsible only for closed PRs. | |
| 565 This should be set if \texttt{responsible} is set, and should also be | |
| 566 left set when a developer quits. | |
| 567 | |
| 568 \item | |
| 569 \texttt{editpr} -- if this is true, the user is allowed to run | |
| 570 \texttt{edit-pr} and make changes to the database. | |
| 571 This should be set for all developers, and only developers, and should | |
| 572 be cleared when a developer quits. | |
| 573 | |
| 574 \item | |
| 575 \texttt{admin} -- if this is true, the user is allowed to perform | |
| 576 administrative tasks. | |
| 577 | |
| 578 \end{itemize} | |
| 579 | |
| 580 Note that while all developers are assumed to have a username, end | |
| 581 users will in general not have one. | |
| 582 | |
| 583 XXX: what's the mechanism for updating user information? | |
| 584 | |
| 585 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
| 586 \section{Administrator Queue} | |
| 587 | |
| 588 The database contains an explicit queue, or in fact several explicit | |
| 589 queues, of issues requiring administrator attention. | |
| 590 The following subsections describe the components of the administrator | |
| 591 queue. | |
| 592 The administrator queue is accessible only to users with the | |
| 593 \texttt{admin} permission bit set. | |
| 594 | |
| 595 \subsection{Comments filed on locked PRs.} | |
| 596 | |
| 597 When a comment is made on a PR that is locked, instead of being | |
| 598 applied to the PR it is placed in the administrator queue for manual | |
| 599 attention. | |
| 600 The possible actions are: | |
| 601 \begin{itemize} | |
| 602 \item defer: put it off for tomorrow; | |
| 603 \item accept: add it to the PR, for valid/intended comments; | |
| 604 \item new: create a new PR instead; | |
| 605 \item reroute: send to another PR instead, for mistyped PR numbers; | |
| 606 \item bounce: return to sender, for non-spam with no clear other choice; | |
| 607 \item discard: erase it, as comments on locked PRs are often spam. | |
| 608 \end{itemize} | |
| 609 | |
| 610 Accepting a comment on a locked PR automatically unlocks it, and by | |
| 611 default also reopens it. | |
| 612 | |
| 613 \subsection{Feedback mail bounces.} | |
| 614 | |
| 615 When bounced mail arrives, Swallowtail examines it to try to determine | |
| 616 which PR and which user it applies to. | |
| 617 If it appears to be a bounce generated from feedback mail (or from | |
| 618 reminder mail) it goes into this queue. | |
| 619 The full mail is retained for inspection. | |
| 620 | |
| 621 The possible actions are: | |
| 622 \begin{itemize} | |
| 623 \item defer: put it off for tomorrow; | |
| 624 \item count: just add one to the number of bounces recorded; | |
| 625 \item changeaddr: change to a different address for the same user; | |
| 626 \item nomail: inhibit sending further mail to the user; | |
| 627 \item discard: delete the mail from the queue. | |
| 628 \end{itemize} | |
| 629 % XXX the count used by ``count'' needs to be described in the user | |
| 630 % data section. | |
| 631 | |
| 632 \subsection{Other mail bounces.} | |
| 633 | |
| 634 Bounced mail that can be associated with a PR and/or user but is not | |
| 635 feedback goes into this queue. | |
| 636 The actions are the same as for feedback bounces. | |
| 637 | |
| 638 \subsection{Junk mail.} | |
| 639 | |
| 640 All other unrecognized mail goes into this queue. | |
| 641 The possible actions are: | |
| 642 \begin{itemize} | |
| 643 \item defer: put it off for tomorrow; | |
| 644 \item forward: forward it somewhere (normally to yourself); | |
| 645 \item discard: erase it. | |
| 646 \end{itemize} | |
| 647 | |
| 648 (XXX: maybe this stuff should just be forwarded on or dumped out into | |
| 649 a mailbox somewhere.) | |
| 650 | |
| 651 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
| 652 \section{Classification Schemes} | |
| 653 | |
| 654 Here is a quick discussion of the classification schemes that we | |
| 655 expect to use, or might use. | |
| 656 | |
|
19
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
657 There are four kinds of classifications: enumerated (the value must be |
|
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
658 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
|
659 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
|
660 hierarchical (like enumerated, but with structure). |
|
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
661 |
|
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
662 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
|
663 want to be tags instead. |
|
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
664 |
| 18 | 665 \subsection{Enumerated classifications} |
| 666 | |
| 667 \paragraph{Category.} | |
| 668 The part of the system affected, in broad terms. | |
| 669 The same as the GNATS ``Category'' field. | |
| 670 This classification is special-cased in some places, at least for now; | |
| 671 in the future it might make sense to allow those places to do matching | |
| 672 on arbitrary classifications. | |
| 673 | |
| 674 \paragraph{Class.} | |
| 675 The GNATS ``Class'' field: \texttt{sw-bug}, \texttt{doc-bug}, | |
| 676 \texttt{change-request}, etc. | |
| 677 | |
| 678 \paragraph{Severity.} | |
| 679 The GNATS ``Severity'' field. | |
| 680 | |
| 681 \paragraph{Priority.} | |
| 682 | |
| 683 The GNATS ``Priority'' field. | |
| 684 | |
|
19
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
685 \subsection{Tag sets.} |
|
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{Release-goals.} |
|
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
688 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
|
689 when planning for a release. |
|
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
690 |
|
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
691 \paragraph{Branch-notes.} |
|
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
692 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
|
693 that can therefore be retired along with branches. |
|
0365c1ab6fd8
Improve description of classification schemes.
David A. Holland
parents:
18
diff
changeset
|
694 |
| 18 | 695 \subsection{Text classifications} |
| 696 | |
| 697 \paragraph{Manpage.} | |
| 698 The name of the nearest man page to where the problem appears to be. | |
| 699 FreeBSD has been using this as a tagging scheme for some time. | |
| 700 | |
| 701 \paragraph{Package.} | |
| 21 | 702 The identity (category/directory form) of the package affected. |
| 18 | 703 (For pkgsrc bugs only.) |
| 704 | |
| 705 \subsection{Hierarchical taxonomies} | |
| 706 | |
| 707 \paragraph{Subsystem.} | |
| 708 The hierarchical taxonomy I've been using for the buglists web page. | |
| 709 | |
| 710 \paragraph{Consequences.} | |
| 711 A hierarchical taxonomy of the results of the problem (annoyance, | |
| 712 system crash, remote root exploit, etc.) | |
| 713 | |
| 714 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
| 715 \section{Other Future Features} | |
| 716 | |
| 717 Some other things that aren't likely to be deployed immediately but | |
| 718 are worth considering later: | |
| 719 | |
| 720 \begin{itemize} | |
| 721 | |
| 722 \item Have a way to note dependencies among PRs, as in 12345 is | |
| 723 stalled until 24680 is fixed. | |
| 724 (This does not occur often enough in practice to be a priority.) | |
| 725 | |
| 726 \item Have a way to massedit a group of PRs; for example, put all PRs | |
| 727 against a particular driver or filesystem or whatever into feedback | |
| 728 after major fixes. | |
| 729 | |
| 730 \item There should be administrator buttons for moving comments to | |
| 731 different PRs, for e.g. misfiled comment notices. | |
| 732 | |
| 733 \item It should be possible for users to set personal tags/priorities | |
| 734 for annotating and/or sorting nag mail. | |
| 735 (E.g. sort by priority, or age, or time since last change, etc.) | |
| 736 | |
|
20
675b7dd62bba
I just thought of another thing for the future list.
David A. Holland
parents:
19
diff
changeset
|
737 \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
|
738 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
|
739 last one that went out. |
|
675b7dd62bba
I just thought of another thing for the future list.
David A. Holland
parents:
19
diff
changeset
|
740 |
| 18 | 741 \item It should be possible to blacklist Cc: of certain addresses |
| 742 (particularly internal lists) in bug traffic. | |
| 743 | |
| 744 \item Any new send-pr script should be configurable by the user with | |
| 745 return addresses and default values for organization and so forth. | |
| 746 | |
| 747 \item It would be nice to be able to track PR status separately (or | |
| 748 semi-separately) for release branches. | |
| 749 However, it isn't clear how to do this without making a cumbersome | |
| 750 mess. | |
| 751 | |
| 752 \item It might be useful to be able to explicitly merge duplicate PRs, | |
| 753 without either losing information or creating a confused mess of | |
| 754 interleaved comments. | |
| 755 | |
| 756 \item It might be worth adding threading for comments. | |
| 757 | |
| 758 \item We should figure out how to make Google see and index the pages | |
| 759 for each PR. | |
| 760 Or maybe just the open ones. | |
| 761 | |
| 762 \item It would be nice if the web page for each PR had browse features | |
| 763 like links for ``show all PRs of this priority'' or ``show all PRs | |
| 764 from this submitter'' and whatnot. | |
| 765 | |
| 766 \item Lists of PRs in the web interface should have a sidebar to let | |
| 767 you narrow the list, and a list of the filters currently applied (like | |
| 768 e.g. NewEgg's product searches). | |
| 769 Also, the sort order should be defined (unlike GNATS) and selectable. | |
| 770 | |
| 771 \item It might be worthwhile to allow PR subscriptions in a brief mode | |
| 772 where all you get is ``Joe commented on PR 12345''. | |
| 773 | |
| 774 \item We will eventually want a way to turn MIME blobs already in the | |
| 775 database into attachments. | |
| 776 | |
| 777 \item Should have per-user tags that are more or less private. | |
| 778 | |
| 779 \item Should have per-user tags that are public. | |
| 780 | |
| 35 | 781 \item In the long run it should be possible to log into the web |
| 782 interface as a developer and do all developer things there instead of | |
| 783 from the command line. | |
| 784 | |
| 18 | 785 |
| 786 \end{itemize} | |
| 787 | |
| 788 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
|
15
c4ee36b629c0
Build bits for docs, and a starting placeholder doc.
David A. Holland
parents:
diff
changeset
|
789 \end{document} |