Mercurial > hg > xemacs-beta
comparison man/gnats/p-admin.texi @ 112:48d667d6f17f r20-1b8
Import from CVS: tag r20-1b8
| author | cvs |
|---|---|
| date | Mon, 13 Aug 2007 09:20:48 +0200 |
| parents | |
| children |
comparison
equal
deleted
inserted
replaced
| 111:164ab62060bf | 112:48d667d6f17f |
|---|---|
| 1 @node Management | |
| 2 @chapter @sc{gnats} Administration | |
| 3 @cindex administering @sc{gnats} | |
| 4 @cindex managing @sc{gnats} | |
| 5 @cindex GNATS management | |
| 6 @cindex duties for @code{gnats-admin} | |
| 7 | |
| 8 In daily usage, @sc{gnats} is self-maintaining. However, there are | |
| 9 various administrative duties which need to be performed periodically: | |
| 10 | |
| 11 @table @emph | |
| 12 @item emptying the @code{pending} directory | |
| 13 @cindex emptying the @code{pending} directory | |
| 14 If a Problem Report arrives with a @samp{>Category:} value that is | |
| 15 unrecognized by the @file{categories} file, or if that field is missing, | |
| 16 @sc{gnats} places the PR in the @w{@file{pending}} directory | |
| 17 (@pxref{Locations,,Where the tools and utilities reside}). @sc{gnats} | |
| 18 has no way of knowing which subdirectory the PR should be filed under. | |
| 19 @sc{gnats} sends a notice to the @code{gnats-admin} and to the party | |
| 20 responsible for that submitter (as listed in the @file{submitters} file) | |
| 21 when this occurs. | |
| 22 | |
| 23 To file these PRs, simply use @code{edit-pr} to repair the problematic | |
| 24 fields in each file in the @file{pending} directory. Be sure to change | |
| 25 the @samp{>Category:} field of the PR from @samp{pending} to an | |
| 26 appropriate category. In many cases the culprit is simply a | |
| 27 typographical error, although it may be necessary sometimes to contact | |
| 28 the submitter of the PR to decipher her or his intentions. | |
| 29 | |
| 30 Should you run out of disk space, there may be an empty PR in the | |
| 31 @file{pending} directory. In that case, look in the file | |
| 32 @w{@file{@var{GNATS_ROOT}/gnats-adm/bug.log}}, which should still contain | |
| 33 the full message that was submitted. | |
| 34 | |
| 35 @item adding new categories | |
| 36 @cindex adding a problem category | |
| 37 @cindex @code{mkcat} | |
| 38 To add a new category, simply insert a new line in the | |
| 39 @w{@file{categories}} file and then run the program @code{mkcat}. | |
| 40 | |
| 41 @emph{Note}: this causes all category lists for @code{send-pr} (except | |
| 42 the one on the local machine) to become outdated. Copy the new list on | |
| 43 to every machine on your network that has @code{send-pr} installed, and | |
| 44 make sure you advise remote submitters that the category list has | |
| 45 changed. @xref{mkcat,,Adding a problem category}. Also | |
| 46 @ref{categories,,The @code{categories} file}. | |
| 47 | |
| 48 @item removing categories | |
| 49 @cindex removing a problem category | |
| 50 @cindex @code{rmcat} | |
| 51 To remove a category, you need to make sure the relevant subdirectory is | |
| 52 empty (in other words, make sure no PRs exist for the category you wish | |
| 53 to remove). You can then remove the category listing from the | |
| 54 @file{categories} file, and invoke | |
| 55 | |
| 56 @smallexample | |
| 57 rmcat @var{category@dots{}} | |
| 58 @end smallexample | |
| 59 | |
| 60 @noindent | |
| 61 to remove @var{category} (any number of categories may be specified on | |
| 62 the command line to @code{rmcat}, so long as they abide by the above | |
| 63 constraints). | |
| 64 | |
| 65 @emph{Note}: this causes all category lists for @code{send-pr} (except | |
| 66 the one on the local machine) to become outdated. Copy the new list on | |
| 67 to every machine on your network that has @code{send-pr} installed, and | |
| 68 make sure you advise remote submitters that the category list has | |
| 69 changed. @xref{rmcat,,Removing a problem category}. Also | |
| 70 @ref{categories,,The @code{categories} file}. | |
| 71 | |
| 72 @item adding and removing maintainers | |
| 73 @cindex adding and removing maintainers | |
| 74 Edit the @file{responsible} file to add a new maintainer or to remove an | |
| 75 existing maintainer. @xref{responsible,,The @code{responsible} file}. | |
| 76 | |
| 77 @item building a distribution of @code{send-pr} | |
| 78 @cindex building a distribution of @code{send-pr} | |
| 79 @cindex @code{mkdist} | |
| 80 You can build a distribution of @code{send-pr} which contains valid | |
| 81 information for your site by invoking the command @code{mkdist}. | |
| 82 @xref{mkdist,,Configuring @code{send-pr} for the outside world}. You | |
| 83 can then distribute your customized @w{@code{send-pr}} to your | |
| 84 customers, friends, relatives, etc., so that they can submit Problem | |
| 85 Reports to your database. | |
| 86 | |
| 87 @item building a new index | |
| 88 @cindex building a new index | |
| 89 @cindex @code{gen-index} | |
| 90 If your index becomes corrupted, or if you wish to generate a new one | |
| 91 for some reason, use the program @code{gen-index} | |
| 92 (@pxref{gen-index,,Regenerating the index}). | |
| 93 | |
| 94 @item pruning log files | |
| 95 @cindex pruning log files | |
| 96 Log files often grow to unfathomable proportions. As with gardening, it | |
| 97 is best to prune these as they grow, lest they take over your disk and | |
| 98 leave you with no room to gather more Problem Reports. If you keep log | |
| 99 files, be sure to keep an eye on them. (@xref{Aliases,,Setting up mail | |
| 100 aliases}.) | |
| 101 @c "gather ye rosebugs while ye may..." | |
| 102 | |
| 103 @item BACKING UP YOUR DATA | |
| 104 @cindex BACK UP YOUR DATA | |
| 105 Any database is only useful if its data remains uncorrupted and safe. | |
| 106 Performing periodic backups ensures that problems like disk crashes and | |
| 107 data corruption are reversible. | |
| 108 | |
| 109 @end table | |
| 110 | |
| 111 @xref{Locations,,Where @sc{gnats} lives}. | |
| 112 | |
| 113 @menu | |
| 114 * Networked management:: Managing GNATS over a network | |
| 115 * Local configuration:: Changing your local configuration | |
| 116 * Admin files:: Administrative data files | |
| 117 * Admin utils:: Administrative utilities | |
| 118 * Internal utils:: Internal utilities | |
| 119 @end menu | |
| 120 | |
| 121 @node Networked management | |
| 122 @section Managing @sc{gnats} over a network | |
| 123 @cindex networked management | |
| 124 @cindex managing @sc{gnats} over a network | |
| 125 | |
| 126 If you have installed the @sc{gnats} user tools on machines around your | |
| 127 local network, there are a few things you need to remember. | |
| 128 | |
| 129 @code{mkcat} and @code{rmcat} do not update the categories list for | |
| 130 other machines on your network which have @code{send-pr} installed, | |
| 131 unless those machines share @var{prefix} with the host machine). To | |
| 132 update these lists, copy the @code{send-pr} categories list to each of | |
| 133 the other hosts. This categories list is | |
| 134 @w{@file{@var{prefix}/lib/gnats/@var{site}}}, where @var{site} is the | |
| 135 name tag for your local site, as specified in the @file{config} file as | |
| 136 @samp{GNATS_SITE} (@pxref{config,,The @code{config} file}). | |
| 137 | |
| 138 It is also important to note that only your local @code{send-pr} has | |
| 139 access to this new information; any copies of @code{send-pr} which you | |
| 140 have distributed to outside submitters now have outdated category lists. | |
| 141 You must either contact your submitters and instruct them to update | |
| 142 their copy of the categories list, which they installed in | |
| 143 @w{@file{@var{prefix}/lib/gnats/@var{support-site}}} from the | |
| 144 distribution you provided, or you must build another distribution of | |
| 145 @code{send-pr} with this new information and redistribute it. | |
| 146 | |
| 147 If you need to use @sc{gnats} utilities, like @code{query-pr} and | |
| 148 @code{edit-pr}, on other systems besides the one where @sc{gnats} itself | |
| 149 resides, @pxref{Installing tools,,Installing the user tools}. | |
| 150 | |
| 151 @c FIXME - anything else? | |
| 152 | |
| 153 @node Local configuration | |
| 154 @section Changing your local configuration | |
| 155 @cindex local configuration | |
| 156 @cindex changing your local configuration | |
| 157 | |
| 158 @xref{Locations,,Where @sc{gnats} lives}. | |
| 159 | |
| 160 Your local configuration is determined by the data files in the | |
| 161 directory @w{@file{@var{GNATS_ROOT}/gnats-adm}}. These can be altered at | |
| 162 any time by editing the pertinent file. | |
| 163 | |
| 164 @table @code | |
| 165 @cindex @code{config} file | |
| 166 @item config | |
| 167 Variables which control certain behavior. @xref{config,,The | |
| 168 @code{config} file}. Behaviors you can change here include | |
| 169 | |
| 170 @itemize @bullet | |
| 171 @item | |
| 172 The address where your site receives Problem Reports. | |
| 173 | |
| 174 @item | |
| 175 The address of the @sc{gnats} administrator. | |
| 176 | |
| 177 @item | |
| 178 The nametag for your Support Site (your organization, company, | |
| 179 group, etc.). | |
| 180 | |
| 181 @item | |
| 182 The nametag for your local Submitter Site. | |
| 183 | |
| 184 @item | |
| 185 The default release for your site. | |
| 186 | |
| 187 @item | |
| 188 The default value for the @samp{>Organization:} field (this value | |
| 189 appears as the default when you run @code{send-pr}). | |
| 190 | |
| 191 @item | |
| 192 Whether or not to remind maintainers if a requisite time period has | |
| 193 passed before they change the state of a Problem Report to | |
| 194 @samp{analyzed}. (Also see @ref{submitters,,The @code{submitters} | |
| 195 file}, and @ref{at-pr,,Timely Reminders}. | |
| 196 | |
| 197 @item | |
| 198 Whether or not to send an automatic acknowledgement to the originator of | |
| 199 a problem report when the @sc{gnats} first receives the PR. | |
| 200 | |
| 201 @item | |
| 202 The value @sc{gnats} assigns to PRs which come in with missing or unknown | |
| 203 values for the @samp{>Submitter-Id:} field. | |
| 204 | |
| 205 @item | |
| 206 Whether or not @sc{gnats} should retain @samp{Received:} | |
| 207 mail headers from incoming mail. | |
| 208 | |
| 209 @item | |
| 210 Whether or not @sc{gnats} is in a mode for debugging. | |
| 211 | |
| 212 @item | |
| 213 The values which define business hours. | |
| 214 @end itemize | |
| 215 | |
| 216 @cindex @code{categories} file | |
| 217 @item categories | |
| 218 The list of categories that @sc{gnats} accepts as valid for the | |
| 219 @samp{>Category:} field, and the maintainers responsible for each | |
| 220 category. Update this file whenever you have a new category, or | |
| 221 whenever a category is no longer valid. You must also update this file | |
| 222 whenever responsiblility for a category changes, or if a maintainer is | |
| 223 no longer valid. @xref{categories,,The @code{categories} file}. Also | |
| 224 see @ref{mkcat,,Adding a new problem category}, and @ref{rmcat,,Removing | |
| 225 a problem category}. | |
| 226 | |
| 227 @cindex @code{responsible} file | |
| 228 @item responsible | |
| 229 The list of maintainers. Update this file whenever you have a new | |
| 230 maintainer, or whenever a maintainer is no longer valid. | |
| 231 @xref{responsible,,The @code{responsible} file}. | |
| 232 | |
| 233 @cindex @code{submitters} file | |
| 234 @item submitters | |
| 235 The list of Submitter Sites from whom @sc{gnats} accepts Problem Reports. | |
| 236 This file is mandatory, although the feature it provides is not; see | |
| 237 @ref{submitters,,The @code{submitters} file}. | |
| 238 @end table | |
| 239 | |
| 240 @menu | |
| 241 * default behavior:: | |
| 242 * config:: The `config' file | |
| 243 * categories:: The `categories' file | |
| 244 * responsible:: The `responsible' file | |
| 245 * submitters:: The `submitters' file | |
| 246 @end menu | |
| 247 | |
| 248 @node default behavior | |
| 249 @subsection Default behavior | |
| 250 | |
| 251 The default behavior for @sc{gnats} is as follows: | |
| 252 | |
| 253 @cindex default behavior | |
| 254 @itemize @bullet | |
| 255 @item | |
| 256 The address where your site receives Problem Reports is @samp{bugs} (a | |
| 257 local address). | |
| 258 | |
| 259 @item | |
| 260 The address of the @sc{gnats} administrator is @samp{gnats-admin} (a local | |
| 261 address). | |
| 262 | |
| 263 @item | |
| 264 The nametag for your Support Site (your organization, company, group, | |
| 265 etc.) is the second-to-last field in your domain name. | |
| 266 | |
| 267 @item | |
| 268 The nametag for your local Submitter Site is the nametag for your | |
| 269 Support Site. | |
| 270 | |
| 271 @item | |
| 272 The default release for your site is @samp{unknown-1.0}. | |
| 273 | |
| 274 @item | |
| 275 The default value for the @samp{>Organization:} field (this value appears as the | |
| 276 default when you run @code{send-pr}) is the nametag for your Support | |
| 277 Site. | |
| 278 | |
| 279 @item | |
| 280 @sc{gnats} reminds maintainers if a requisite time period has passed | |
| 281 before they change the state of a Problem Report to @samp{analyzed}. | |
| 282 | |
| 283 @item | |
| 284 An automatic acknowledgement is sent to the originator of a problem | |
| 285 report when the @sc{gnats} first receives the PR. | |
| 286 | |
| 287 @item | |
| 288 The value @sc{gnats} assigns to the @samp{>Submitter-Id:} field in PRs | |
| 289 which arrive with missing or unknown values for that field is | |
| 290 @samp{unknown}. | |
| 291 | |
| 292 @item | |
| 293 @samp{Received@dots{}} mail headers are retained. | |
| 294 | |
| 295 @item | |
| 296 @sc{gnats} is not in a debugging mode. | |
| 297 | |
| 298 @item | |
| 299 @dfn{business hours} are defined as 8:00am to 5:00pm, Monday through | |
| 300 Friday. | |
| 301 @end itemize | |
| 302 | |
| 303 | |
| 304 @node config | |
| 305 @subsection The @code{config} file | |
| 306 @cindex @code{config} file | |
| 307 | |
| 308 Much of the behavior @sc{gnats} exhibits depends on the values of fields | |
| 309 in the file @w{@file{@var{GNATS_ROOT}/gnats-adm/config}}. The | |
| 310 @file{config} file contains a list of variables (using Bourne-shell | |
| 311 syntax) which control the following behavior. These values can be | |
| 312 changed at any time; the new values take effect for all subsequent | |
| 313 iterations of the tools. | |
| 314 | |
| 315 @table @code | |
| 316 @cindex @code{GNATS_ADDR} | |
| 317 @item GNATS_ADDR="@var{address}" | |
| 318 The address where your site receives Problem Reports. This address is | |
| 319 aliased in the file @w{@file{/etc/aliases}} so that it directs incoming | |
| 320 mail into @code{queue-pr} (@pxref{Installing utils,,Installing the | |
| 321 utilities}). | |
| 322 | |
| 323 The default is @samp{bugs} (a local address). | |
| 324 | |
| 325 @cindex @code{GNATS_ADMIN} | |
| 326 @item GNATS_ADMIN="@var{address}" | |
| 327 The address of the @sc{gnats} administrator. Normally this is set to | |
| 328 @samp{gnats-admin}, which is an alias in @file{/etc/aliases} that points | |
| 329 toward the person responsible for administrating @sc{gnats}. | |
| 330 @xref{Installing utils,,Installing the utilities}. | |
| 331 | |
| 332 The default is @samp{gnats-admin} (a local address). | |
| 333 | |
| 334 @cindex @code{GNATS_SITE} | |
| 335 @item GNATS_SITE="@var{site}" | |
| 336 The nametag for your Support Site (your organization, company, group, | |
| 337 etc.). This nametag should also appear in the @file{submitters} file, | |
| 338 so that users at your site can submit Problem Reports locally. | |
| 339 | |
| 340 @var{site} is also used as the name of the file containing a valid | |
| 341 category list for your site. This file is installed locally as | |
| 342 @w{@file{@var{prefix}/lib/gnats/@var{site}}}. @emph{Warning:} if you | |
| 343 change this variable after @sc{gnats} is installed, you must also change | |
| 344 the name of this file, as well as the name of the alias for your local | |
| 345 submitters (@pxref{Aliases,,Setting up mail aliases}). | |
| 346 | |
| 347 The default is the second-to-last field in your domain name. For | |
| 348 example, if your domain name is @w{@samp{unleaded.truckstop.org}}, your | |
| 349 default @var{site} is @w{@samp{truckstop}}. | |
| 350 | |
| 351 @cindex @code{SUBMITTER} | |
| 352 @item SUBMITTER="@var{submitter-id}" | |
| 353 The nametag for your local Submitter Site (this value appears as the | |
| 354 default value for @samp{>Submitter-Id} when you run @code{send-pr}). | |
| 355 Even though you are a Support Site, if you submit Problem Reports to | |
| 356 your own organization you become a Submitter Site. The value | |
| 357 @var{submitter-id} is the default value for the @samp{>Submitter-Id:} | |
| 358 field that your maintainers see when they submit Problem Reports | |
| 359 locally. | |
| 360 | |
| 361 The default is the value of @samp{GNATS_SITE}. | |
| 362 | |
| 363 @cindex @code{DEFAULT_RELEASE} | |
| 364 @item DEFAULT_RELEASE="@var{release}" | |
| 365 The default release for your site (this value appears as the default | |
| 366 value for @samp{>Release:} when you run @code{send-pr}). | |
| 367 | |
| 368 The default is @samp{unknown-1.0}. | |
| 369 | |
| 370 @cindex @code{DEFAULT_ORGANIZATION} | |
| 371 @item DEFAULT_ORGANIZATION="@var{text}" | |
| 372 The default value for the @samp{>Organization:} field (this value | |
| 373 appears as the default when you run @code{send-pr}). | |
| 374 | |
| 375 The default is the value of @samp{GNATS_SITE}. | |
| 376 | |
| 377 @c FIXME - where else to mention this stuff? | |
| 378 @cindex @code{NOTIFY} | |
| 379 @item NOTIFY=@var{boolean} | |
| 380 Determines whether or not to remind maintainers if a requisite time | |
| 381 period has passed before they change the state of a Problem Report to | |
| 382 @samp{analyzed}. This feature uses the program @code{at-pr}; see | |
| 383 @ref{at-pr,,Timely Reminders}. | |
| 384 | |
| 385 This requisite time is determined for each submitter individually; see | |
| 386 @ref{submitters,,The @code{submitters} file}. The time is measured in | |
| 387 @dfn{business hours}, which by default are 8:00am to 5:00pm, Monday | |
| 388 through Friday. Business hours can be redefined by changing the | |
| 389 variables @code{BDAY_START}, @code{BDAY_END}, @code{BWEEK_START}, and | |
| 390 @code{BWEEK_END} in the @file{config} file (see below). | |
| 391 | |
| 392 If @var{boolean} is @samp{1}, this feature is active. If @var{boolean} | |
| 393 is @samp{0}, the feature is turned off. The default value for | |
| 394 @samp{NOTIFY} is @samp{1}. | |
| 395 | |
| 396 @cindex @code{ACKNOWLEDGE} | |
| 397 @item ACKNOWLEDGE=@var{boolean} | |
| 398 Determines whether or not to send an automatic acknowledgement to the | |
| 399 originator of a problem report when the @sc{gnats} first receives the PR. | |
| 400 | |
| 401 If @var{boolean} is @samp{1}, this feature is active. If @var{boolean} | |
| 402 is @samp{0}, the feature is turned off. The default for | |
| 403 @samp{ACKNOWLEDGE} is @samp{1}. | |
| 404 | |
| 405 The acknowledgment is of the form: | |
| 406 | |
| 407 @smallexample | |
| 408 @group | |
| 409 To: @var{your-address} | |
| 410 From: gnats | |
| 411 Subject: Re: @var{category}/@var{gnats-id}:@var{Synopsis} | |
| 412 In-Reply-To: Your message of @var{date} | |
| 413 | |
| 414 Thank you very much for your problem report. | |
| 415 It has the internal identification: @var{category}/@var{gnats-id} | |
| 416 The individual assigned to look at your bug is: | |
| 417 @var{responsible} | |
| 418 | |
| 419 Category: @var{category of the PR} | |
| 420 Responsible: @var{responsible} | |
| 421 Synopsis: @var{Synopsis from submitted PR} | |
| 422 Arrival-Date: @var{arrival date} | |
| 423 @end group | |
| 424 @end smallexample | |
| 425 | |
| 426 @cindex @code{DEFAULT_SUBMITTER} | |
| 427 @item DEFAULT_SUBMITTER="submitter-id" | |
| 428 The value @sc{gnats} assigns to PRs which come in with missing or unknown | |
| 429 values for the @samp{>Submitter-Id:} field. This value must also appear | |
| 430 in the @file{submitters} file; see @ref{submitters,,The | |
| 431 @code{submitters} file}. | |
| 432 | |
| 433 @cindex disabling @var{submitter-id} | |
| 434 To disable the feature of @sc{gnats} which tracks the | |
| 435 @samp{>Submitter-Id:}, simply alter the @file{submitters} file to only | |
| 436 contain the @var{submitter-id} value which appears in | |
| 437 @w{@code{DEFAULT_SUBMITTER}}, and and instruct your submitters to ignore | |
| 438 the field. | |
| 439 | |
| 440 The default value for @samp{DEFAULT_SUBMITTER} is @samp{unknown}. | |
| 441 | |
| 442 @cindex @code{KEEP_RECEIVED_HEADERS} | |
| 443 @item KEEP_RECEIVED_HEADERS=@var{boolean} | |
| 444 Determines whether or not @sc{gnats} should retain the | |
| 445 @w{@samp{Received:}} mail headers from incoming mail. These headers | |
| 446 often take up a lot of space, and they are seldom used. | |
| 447 | |
| 448 If @var{boolean} is @samp{1}, this feature is active. If @var{boolean} | |
| 449 is @samp{0}, the feature is turned off. The default value for | |
| 450 @samp{KEEP_RECEIVED_HEADERS} is @samp{1}. | |
| 451 | |
| 452 @item DEBUG_MODE=@var{boolean} | |
| 453 Determines whether or not @sc{gnats} is operating in a mode for | |
| 454 debugging. When @var{boolean} is @samp{1}, @sc{gnats} fowards all mail | |
| 455 to the @sc{gnats} administrator, @w{@code{gnats-admin}}. | |
| 456 | |
| 457 @cindex business hours | |
| 458 @item BDAY_START=@var{integer} | |
| 459 @itemx BDAY_END=@var{integer} | |
| 460 @itemx BWEEK_START=@var{integer} | |
| 461 @itemx BWEEK_END=@var{integer} | |
| 462 The definition of @dfn{business hours}. These values are only used if | |
| 463 @code{NOTIFY} is set to @samp{1} in the @file{config} file (see above). | |
| 464 | |
| 465 By default, business hours are 8:00am to 5:00pm Monday through Friday, | |
| 466 local time. | |
| 467 | |
| 468 @table @code | |
| 469 @item BDAY_START=@var{integer} | |
| 470 Defines the hour of the day when business hours begin. @var{integer} | |
| 471 values must fall between @samp{0} (midnight) and @samp{23} (11:00pm). | |
| 472 The default is @samp{8} (8:00am). | |
| 473 | |
| 474 @item BDAY_END=@var{integer} | |
| 475 Defines the hour of the day when business hours end. @var{integer} | |
| 476 values must fall between @samp{0} (midnight) and @samp{23} (11:00pm). | |
| 477 The default is @samp{17} (5:00pm). | |
| 478 | |
| 479 @item BWEEK_START=@var{integer} | |
| 480 Defines the beginning day of the business week. @var{integer} values | |
| 481 must fall between @samp{0} (Sunday) and @samp{6} (Saturday). The | |
| 482 default is @samp{1} (Monday). | |
| 483 | |
| 484 @item BWEEK_END=@var{integer} | |
| 485 Defines the ending day of the business week. @var{integer} values must | |
| 486 fall between @samp{0} (Sunday) and @samp{6} (Saturday). The default is | |
| 487 @samp{5} (Friday). | |
| 488 @end table | |
| 489 | |
| 490 @end table | |
| 491 | |
| 492 @node categories | |
| 493 @subsection The @code{categories} file | |
| 494 @cindex @code{categories} file | |
| 495 | |
| 496 The @file{categories} file contains a list of problem categories, | |
| 497 specific to your site, which @sc{gnats} tracks. This file also matches | |
| 498 responsible people with these categories. You must edit this file | |
| 499 initially, creating valid categories and then running @code{mkcat} to | |
| 500 create the corresponding subdirectories of @w{@code{@var{GNATS_ROOT}}} | |
| 501 and update the valid categories list for @w{@code{send-pr}}. For | |
| 502 instructions on running @code{mkcat}, see @ref{mkcat,,Adding a problem | |
| 503 category}. | |
| 504 | |
| 505 To create a new category, log in as @sc{gnats}, add a line to this file, | |
| 506 and run @code{mkcat}. Lines beginning with @samp{#} are ignored. | |
| 507 | |
| 508 A line in the @file{categories} file consists of four fields delimited | |
| 509 by colons, as follows: | |
| 510 | |
| 511 @smallexample | |
| 512 @var{category}:@var{description}:@var{responsible}:@var{notify} | |
| 513 @end smallexample | |
| 514 | |
| 515 @noindent | |
| 516 @table @var | |
| 517 @item category | |
| 518 A unique category name, made up of text characters. This name cannot | |
| 519 contain spaces or any of the following characters: | |
| 520 | |
| 521 @smallexample | |
| 522 ! $ & * ( ) @{ @} [ ] ` ' " ; : < > ~ | |
| 523 @end smallexample | |
| 524 | |
| 525 @noindent | |
| 526 Ideally, category names should not contain commas or begin with periods. | |
| 527 Each line has a corresponding subdirectory in the main @sc{gnats} | |
| 528 directory (@var{GNATS_ROOT}). | |
| 529 | |
| 530 @ignore | |
| 531 It is possible that if you set up the database with categories | |
| 532 which contain characters that describe subdirectories, such as a slash | |
| 533 (@key{/}) in @sc{Unix}, you could effectively build subdirectories | |
| 534 within each category, and @sc{gnats} would read and write to these | |
| 535 files as it would any other. This is not recommended. It doesn't | |
| 536 break any of the existing tools, and is a fine way to keep category | |
| 537 directories from growing too large. It is, however, quite untested. | |
| 538 @end ignore | |
| 539 | |
| 540 @item description | |
| 541 A terse textual description of the category. | |
| 542 | |
| 543 @item responsible | |
| 544 The name tag of the party responsible for this category of problems, as | |
| 545 listed in the @file{responsible} file (@pxref{responsible,,The | |
| 546 @code{responsible} file}). | |
| 547 | |
| 548 @item notify | |
| 549 One or more other parties which should be notified when a Problem Report | |
| 550 with this category arrives, such as a project manager, other members of | |
| 551 the same project, other interested parties, or even log files. These | |
| 552 should be separated with commas. | |
| 553 @end table | |
| 554 | |
| 555 A good strategy for configuring this file is to have a different | |
| 556 category for each product your organization supports or wishes to track | |
| 557 information for, or perhaps with sub-categories within each category. | |
| 558 For instance, if you wish to track documentation problems in a variety of | |
| 559 areas, you could have entries such as | |
| 560 | |
| 561 @smallexample | |
| 562 doc:General Doc Questions:myboss:me,barney | |
| 563 doc-rock:Doc for ROCK program:me:myboss | |
| 564 doc-stone:Docs for STONE utils:barney:fred | |
| 565 doc-local:in-house documentation:me:doc-local-log | |
| 566 @end smallexample | |
| 567 | |
| 568 In the above example, the nametags @samp{myboss}, @samp{me}, | |
| 569 @samp{fred}, and @samp{barney} must be defined in the @file{responsible} | |
| 570 file (@pxref{responsible,,The @code{responsible} file}). | |
| 571 | |
| 572 Problem Reports with a category of @samp{doc} are sent to the local mail | |
| 573 address (or alias) @samp{myboss}, and also sent to the addresses | |
| 574 @samp{me} and @samp{barney}. PRs with a category of @samp{doc-rock} are | |
| 575 sent to the local addresses @samp{me} and @samp{myboss} only, while PRs | |
| 576 with the category @samp{doc-stone} are sent to @samp{fred} as well as to | |
| 577 @samp{barney}. PRs with a category of @samp{doc-local} are sent only to | |
| 578 @samp{me}, and are also filed in @code{doc-local-log} (in this case, an | |
| 579 alias should be set up in @file{/etc/aliases} to reflect a location for | |
| 580 the log file, such as @w{@samp{doc-local-log: /users/me/local-log}}). | |
| 581 | |
| 582 Whenever you add a new category, be sure to run @code{mkcat} to create a | |
| 583 subdirectory for it and update the local categories list. | |
| 584 | |
| 585 Only one category must be present for @sc{gnats} to function: | |
| 586 | |
| 587 @smallexample | |
| 588 pending:Category for faulty PRs: gnats-admin: | |
| 589 @end smallexample | |
| 590 | |
| 591 @cindex @code{pending} file | |
| 592 The @file{pending} directory is created automatically when you run | |
| 593 @w{@samp{make install}} (@pxref{Configure and make,,Configuring and | |
| 594 compiling the software}). | |
| 595 | |
| 596 @node responsible | |
| 597 @subsection The @code{responsible} file | |
| 598 @cindex @code{responsible} file | |
| 599 | |
| 600 This file contains a list of the responsible parties. Lines beginning | |
| 601 with @samp{#} are ignored. Each entry contains three fields, separated | |
| 602 by colons: | |
| 603 | |
| 604 @smallexample | |
| 605 @var{responsible}:@var{full-name}:@var{mail-address} | |
| 606 @end smallexample | |
| 607 | |
| 608 @noindent | |
| 609 @table @var | |
| 610 @item responsible | |
| 611 A name-tag description of the party in question, such as her or his user | |
| 612 name, or the name of the group. This name is listed in the PR in | |
| 613 the @samp{>Responsible:} field. | |
| 614 | |
| 615 @item full-name | |
| 616 The full name of the party (``Charlotte Bronte''; ``Compiler Group''). | |
| 617 | |
| 618 @item mail-address | |
| 619 The full, valid mail address of the party. This field is only necessary | |
| 620 if the responsible party has no local mail address or alias. | |
| 621 @end table | |
| 622 | |
| 623 @noindent | |
| 624 A sample @file{responsible} listing might be: | |
| 625 | |
| 626 @smallexample | |
| 627 ren:Ren Hoek: | |
| 628 stimpy:Stimpson J. Cat:stimpy@@lederhosen.org | |
| 629 @end smallexample | |
| 630 | |
| 631 Here, @code{ren} is a local user. @code{stimpy} is remote, so his full | |
| 632 address must be specified. | |
| 633 | |
| 634 The following entry must be present for @sc{gnats} to function: | |
| 635 | |
| 636 @smallexample | |
| 637 gnats-admin: GNATS administrator: | |
| 638 @end smallexample | |
| 639 | |
| 640 @noindent | |
| 641 (@code{gnats-admin} is a mail alias, so for this purpose | |
| 642 @code{gnats-admin} is a local address.) | |
| 643 | |
| 644 @node submitters | |
| 645 @subsection The @code{submitters} file | |
| 646 @cindex @code{submitters} file | |
| 647 | |
| 648 This is a database of sites which submit bugs to your support site. It | |
| 649 contains six fields delineated by colons. Lines beginning with @samp{#} | |
| 650 will be ignored. | |
| 651 | |
| 652 Entries are of the format: | |
| 653 | |
| 654 @smallexample | |
| 655 @var{submitter-id}:@var{name}:@var{type}:@var{resp-time}:@var{contact}:@var{notify} | |
| 656 @end smallexample | |
| 657 | |
| 658 @noindent | |
| 659 @table @var | |
| 660 @item submitter-id | |
| 661 A unique identifier for a specific site or other entity who submits | |
| 662 Problem Reports. | |
| 663 | |
| 664 @item name | |
| 665 A textual description of this entity. | |
| 666 | |
| 667 @item type | |
| 668 Optional description for the type of relationship this submitter to your | |
| 669 support site. This could indicate a contract type, a level of | |
| 670 expertise, etc., or it can remain blank. | |
| 671 | |
| 672 @item resp-time | |
| 673 Optional quoted response time, in @dfn{business hours}. @sc{gnats} is | |
| 674 capable of reminding responsible parties when Problem Reports marked | |
| 675 with a @samp{>Severity} value of @samp{critical}, or those with a | |
| 676 @samp{>Severity} of @samp{serious} and a @samp{>Priority} value of | |
| 677 @samp{high}, are neglected for a certain period. This argument defines | |
| 678 that response period for each @var{submitter-id}. Business hours are | |
| 679 defined by default as 8:00am to 5:00pm, Monday through Friday. For | |
| 680 example, three business days would be equal to 24 business hours. | |
| 681 | |
| 682 This function is active if the @code{NOTIFY} field is defined as | |
| 683 @samp{1} in the @file{config} file (@pxref{Local configuration,,Changing | |
| 684 your local configuration}). If @code{NOTIFY} is @samp{0}, this field is | |
| 685 ignored. For information on @code{at-pr}, the program which sends out | |
| 686 this reminder, see @ref{at-pr,,Timely Reminders}. | |
| 687 | |
| 688 @item contact | |
| 689 The name tag of the main @dfn{contact} at the Support Site for this | |
| 690 submitter. This contact should be in the @file{responsible} file | |
| 691 (@pxref{responsible,,The @code{responsible} file}). Incoming bugs from | |
| 692 @var{submitter} are sent to this contact. Optionally, this field can be | |
| 693 left blank. | |
| 694 | |
| 695 @item notify | |
| 696 Any other parties who should receive copies of Problem Reports sent in | |
| 697 by @var{submitter}. | |
| 698 @end table | |
| 699 | |
| 700 A few example entries in the @file{submitters} file: | |
| 701 | |
| 702 @smallexample | |
| 703 univ-hell: University of Hades:eternal:3:beelzebub:lucifer | |
| 704 tta: Telephones and Telegraphs of America:support:720:dave: | |
| 705 @end smallexample | |
| 706 | |
| 707 @noindent | |
| 708 In this example, when a PR comes in from the University of Hades (who | |
| 709 has an eternal contract), it should have @samp{univ-hell} in its | |
| 710 @samp{Submitter-Id} field. This Problem Report goes to @code{beelzebub} | |
| 711 (who should be in the @file{responsible} file), and if it is not | |
| 712 analyzed within three business hours a reminder message is sent. | |
| 713 @code{lucifer} also receives a copy of the bug, and a copy of the | |
| 714 reminder message as well (if it is sent). When Telephones and | |
| 715 Telegraphs of America utilizes their support contract and submits a bug, | |
| 716 a copy is sent only to @code{dave}, who has 720 business hours to return | |
| 717 an analysis before a reminder is sent. | |
| 718 | |
| 719 @cindex disabling @var{submitter-id} | |
| 720 To disable the feature of @sc{gnats} which tracks the | |
| 721 @samp{>Submitter-Id:}, simply alter the @file{submitters} file to only | |
| 722 contain the @var{submitter-id} value which appears as the | |
| 723 @samp{DEFAULT_SUBMITTER} value in the @file{config} file | |
| 724 (@pxref{config,,The @code{config} file}), and instruct your submitters | |
| 725 to ignore the field. | |
| 726 | |
| 727 @node Admin files | |
| 728 @section Administrative data files | |
| 729 @cindex admin files | |
| 730 @cindex files used for @sc{gnats} administration | |
| 731 | |
| 732 The following files are located in @file{@var{GNATS_ROOT}/gnats-adm}, | |
| 733 where @var{GNATS_ROOT} is the resident directory of @sc{gnats}. These | |
| 734 files are maintained by @sc{gnats}; you should never touch them. | |
| 735 | |
| 736 @menu | |
| 737 * index file:: The `index' file | |
| 738 * current file:: The `current' file | |
| 739 @end menu | |
| 740 | |
| 741 @node index file | |
| 742 @subsection The @code{index} file | |
| 743 @cindex @code{index} file | |
| 744 | |
| 745 The index is used to accelerate searches on the database by | |
| 746 @code{query-pr} and @code{edit-pr}. This file is not created until the | |
| 747 first PR comes in. It is then kept up to date by @sc{gnats}; you should | |
| 748 never touch this file. | |
| 749 | |
| 750 Any searches on subjects contained in the index are much faster than | |
| 751 searches which depend on data not in the index. The index contains | |
| 752 single-line entries for the following fields, in order, separated by | |
| 753 colons (@samp{:}) except for @samp{>Category:} and @samp{>Number:}, | |
| 754 which are separated by a slash (@samp{/}) (the @samp{>} and @samp{:} | |
| 755 Problem Report fieldname delimiters have been removed for the sake of | |
| 756 brevity and readability):: | |
| 757 | |
| 758 @smallexample | |
| 759 Category Number Submitter-Id | |
| 760 Responsible State Confidential | |
| 761 Severity Priority | |
| 762 @end smallexample | |
| 763 | |
| 764 To see an example index, run @code{gen-index} without any options | |
| 765 (@pxref{gen-index,,Regenerating the index}). | |
| 766 | |
| 767 @node current file | |
| 768 @subsection The @code{current} file | |
| 769 @cindex @code{current} file | |
| 770 | |
| 771 This file contains the last serial number assigned to an incoming PR. | |
| 772 It is used internally by @sc{gnats}; you need never touch this file. | |
| 773 | |
| 774 @node Admin utils | |
| 775 @section Administrative utilities | |
| 776 @cindex administrative utilities | |
| 777 | |
| 778 These tools are used by the @sc{gnats} administrator as part of the | |
| 779 periodic maintenance and configuration of @sc{gnats}. | |
| 780 @xref{Management,,@sc{gnats} Administration}. | |
| 781 | |
| 782 @menu | |
| 783 * mkcat:: Adding a problem category | |
| 784 * rmcat:: Removing a problem category | |
| 785 * gen-index:: Regenerating the index | |
| 786 * mkdist:: Configuring send-pr for the outside world | |
| 787 @end menu | |
| 788 | |
| 789 @node mkcat | |
| 790 @subsection Adding a problem category | |
| 791 @cindex @code{mkcat} | |
| 792 @cindex adding a problem category | |
| 793 @cindex new problem categories | |
| 794 @cindex @code{categories} file | |
| 795 | |
| 796 To add new categories to the database: | |
| 797 | |
| 798 @enumerate 1 | |
| 799 @item | |
| 800 Add a line to the @file{categories} file under | |
| 801 @w{@file{@var{GNATS_ROOT}/gnats-adm}} for each new category. | |
| 802 @xref{categories,,The @code{categories} file}. | |
| 803 | |
| 804 @item | |
| 805 Run @code{mkcat}. @code{mkcat} creates a directory under | |
| 806 @w{@var{GNATS_ROOT}} for any new categories which appear in the | |
| 807 @file{categories} file. @code{mkcat} also recreates the list of valid | |
| 808 categories for both your locally installed @code{send-pr} and for the | |
| 809 @code{send-pr} distribution template in | |
| 810 @w{@file{@var{prefix}/lib/gnats/dist}} (@pxref{Locations,,Where @sc{gnats} | |
| 811 lives}. | |
| 812 @end enumerate | |
| 813 | |
| 814 @emph{Note:} @code{mkcat} does not update the categories list for other | |
| 815 machines on your network which have @code{send-pr} installed (unless | |
| 816 the two machines share the directory @var{prefix}). | |
| 817 @xref{Networked management,,Managing @sc{gnats} over a network}. | |
| 818 | |
| 819 It is also important to note that only your local @code{send-pr} has | |
| 820 access to this new information; any copies of @code{send-pr} which you | |
| 821 have distributed to outside submitters now have outdated category lists. | |
| 822 You must either contact your submitters and instruct them to update | |
| 823 their copy of the categories list, which they installed in | |
| 824 @w{@file{@var{prefix}/lib/gnats/@var{support-site}}} (@emph{Note:} the | |
| 825 value for @var{prefix} may be different from yours) from the | |
| 826 distribution you provided, or you must build another distribution of | |
| 827 @code{send-pr} with this new information and redistribute it | |
| 828 (@pxref{mkdist,,Configuring @code{send-pr} for the outside world}). | |
| 829 | |
| 830 @node rmcat | |
| 831 @subsection Removing a problem category | |
| 832 @cindex @code{rmcat} | |
| 833 @cindex removing a problem category | |
| 834 @cindex @code{categories} file | |
| 835 | |
| 836 To remove a category from the database: | |
| 837 | |
| 838 @enumerate 1 | |
| 839 @item | |
| 840 Remove the Problem Reports from the subdirectories corresponding to the | |
| 841 categories you wish to remove, or assign the PRs to new categories. All | |
| 842 PRs for a given category reside in | |
| 843 @w{@file{@var{GNATS_ROOT}/@var{category}}}. Make sure you do this for | |
| 844 each category you wish to remove. | |
| 845 | |
| 846 @item | |
| 847 Run @code{rmcat} using | |
| 848 | |
| 849 @smallexample | |
| 850 rmcat @var{category} [ @var{category@dots{}} ] | |
| 851 @end smallexample | |
| 852 | |
| 853 @noindent | |
| 854 where @var{category} is the category you wish to remove. You can | |
| 855 specify as many categories as you wish as long as each category has no | |
| 856 PRs associated with it. @code{rmcat} removes the directory under | |
| 857 @w{@var{GNATS_ROOT}} where the Problem Reports for that category had been | |
| 858 stored. @code{rmcat} also deletes the category from the list of valid | |
| 859 categories for both your locally installed @code{send-pr} and for the | |
| 860 @code{send-pr} distribution template in | |
| 861 @w{@file{@var{prefix}/lib/gnats/dist}} (@pxref{Locations,,Where @sc{gnats} | |
| 862 lives}). | |
| 863 @end enumerate | |
| 864 | |
| 865 @emph{Note:} @code{rmcat} does not update the categories list for other | |
| 866 machines on your network which have @code{send-pr} installed. | |
| 867 @xref{Networked management,,Managing @sc{gnats} over a network}. | |
| 868 | |
| 869 It is also important to note that only your local @code{send-pr} has | |
| 870 access to this new information; any copies of @code{send-pr} which you | |
| 871 have distributed to outside submitters now have outdated category lists. | |
| 872 You must either contact your submitters and instruct them to update | |
| 873 their copy of the categories list, which they installed in | |
| 874 @w{@file{@var{prefix}/lib/gnats/@var{support-site}}} (@emph{Note:} the | |
| 875 value for @var{prefix} may be different from yours) from the | |
| 876 distribution you provided, or you must build another distribution of | |
| 877 @code{send-pr} with this new information and redistribute it | |
| 878 (@pxref{mkdist,,Configuring @code{send-pr} for the outside world}). | |
| 879 | |
| 880 @c FIXME! Should we suggest this? | |
| 881 @ignore | |
| 882 To reassign a group of categories.... | |
| 883 | |
| 884 (The idea is to call "query-pr --full", run the output through sed, and | |
| 885 then throw it at pr-edit. This approach is untested, and may be unhealthy.) | |
| 886 | |
| 887 @end ignore | |
| 888 | |
| 889 @node gen-index | |
| 890 @subsection Regenerating the index | |
| 891 @cindex @code{gen-index} | |
| 892 @cindex @code{index} file | |
| 893 | |
| 894 If your @file{index} file becomes corrupted, or if you need a copy of | |
| 895 the current index for some reason, use | |
| 896 | |
| 897 @smallexample | |
| 898 gen-index [ -n | --numeric ] | |
| 899 [ -d @var{directory} | --directory=@var{directory} ] | |
| 900 [ -c @var{filename} | --catfile=@var{filename} ] | |
| 901 [ -o @var{filename} | --outfile=@var{filename} ] | |
| 902 [ -h | --help] [ -V | --version ] | |
| 903 @end smallexample | |
| 904 | |
| 905 @noindent | |
| 906 With no options, @code{gen-index} generates an index that is ordered the | |
| 907 same as the order of the categories as they appear in the | |
| 908 @file{categories} file, and prints it to standard output. The options | |
| 909 are: | |
| 910 | |
| 911 @table @code | |
| 912 @item -n | |
| 913 @itemx --numeric | |
| 914 Sorts index entries numerically. | |
| 915 | |
| 916 @item -d @var{directory} | |
| 917 @itemx --directory=@var{directory} | |
| 918 Uses @var{directory} as the directory containing the database, by | |
| 919 default @w{@var{GNATS_ROOT}} (@pxref{Locations,,Where @sc{gnats} lives}). | |
| 920 | |
| 921 @item -o @var{filename} | |
| 922 @itemx --outfile=@var{filename} | |
| 923 Places output in @var{filename} rather than sending it to standard | |
| 924 output. | |
| 925 | |
| 926 @item -c @var{filename} | |
| 927 @itemx --catfile=@var{filename} | |
| 928 Point to @var{filename}, the file listing the valid categories. | |
| 929 | |
| 930 @item -h | |
| 931 @itemx --help | |
| 932 Prints the usage for @code{gen-index}. | |
| 933 | |
| 934 @item -V | |
| 935 @itemx --version | |
| 936 Prints the version number for @code{gen-index}. | |
| 937 @end table | |
| 938 | |
| 939 @node mkdist | |
| 940 @subsection Configuring @code{send-pr} for the outside world | |
| 941 @cindex configuring @code{send-pr} for the outside world | |
| 942 @cindex invoking @code{mkdist} | |
| 943 @cindex using @code{mkdist} | |
| 944 | |
| 945 Now that @sc{gnats} is up and running on your system, you probably want | |
| 946 to distribute @code{send-pr} to all your friends, relatives, enemies, | |
| 947 etc. so they can more easily submit bugs to your organization. To do | |
| 948 this, create a new directory @var{dist-directory} to hold the | |
| 949 distribution. Then run the program | |
| 950 | |
| 951 @smallexample | |
| 952 mkdist --release=@var{release} @var{dist-directory} | |
| 953 @end smallexample | |
| 954 | |
| 955 @noindent | |
| 956 This populates @var{dist-directory} with a full distribution of the | |
| 957 program @code{send-pr}, including a @file{Makefile} and all the | |
| 958 @code{send-pr} documentation. You can then simply package up this | |
| 959 directory and send it to your bug report submitters. For example, | |
| 960 when logged in as @code{gnats} you can do the following: | |
| 961 | |
| 962 @smallexample | |
| 963 mkdir new-dist | |
| 964 mkdist --release=tools-1.2 new-dist | |
| 965 tar cvf send-pr.tar new-dist | |
| 966 @end smallexample | |
| 967 | |
| 968 This creates a file called @file{send-pr.tar} which contains a full | |
| 969 distribution of @code{send-pr} customized for your site, with a default | |
| 970 release number of @samp{tools-1.2}. You can then place this onto a disk | |
| 971 or tape and send it to your submitters, or instruct your submitters to | |
| 972 download it using @code{ftp}. | |
| 973 | |
| 974 If you only have one submitter, you can set the Submitter ID in the | |
| 975 send-pr script by specifying the --submitter option to mkdist. If you | |
| 976 do this, the submitter will not have to run install-sid. | |
| 977 | |
| 978 @node Internal utils | |
| 979 @section Internal utilities | |
| 980 @cindex internal utilities | |
| 981 | |
| 982 These tools are used internally by @sc{gnats}. You should never need to | |
| 983 run these by hand; however, a complete understanding may help you locate | |
| 984 problems with the @sc{gnats} tools or with your local implementation. | |
| 985 | |
| 986 @menu | |
| 987 * queue-pr:: Handling incoming traffic | |
| 988 * file-pr:: Processing incoming traffic | |
| 989 * at-pr:: Timely reminders | |
| 990 * pr-edit:: The edit-pr driver | |
| 991 * pr-addr:: Address retrieval | |
| 992 @end menu | |
| 993 | |
| 994 @node queue-pr | |
| 995 @subsection Handling incoming traffic | |
| 996 @cindex @code{queue-pr} | |
| 997 @cindex handling incoming traffic | |
| 998 | |
| 999 The program @code{queue-pr} handles traffic coming into @sc{gnats}. | |
| 1000 @code{queue-pr} queues incoming Problem Reports in the directory | |
| 1001 @w{@file{@var{GNATS_ROOT}/gnats-queue}}, and then periodically (via | |
| 1002 @code{cron}) passes them on to @code{file-pr} to be filed in the | |
| 1003 @sc{gnats} database. @xref{Installation,,Installing @sc{gnats}}. | |
| 1004 | |
| 1005 The usage for @code{queue-pr} is as follows: | |
| 1006 | |
| 1007 @smallexample | |
| 1008 queue-pr [ -q | --queue ] [ -r | --run ] | |
| 1009 [ -f @var{filename} | --file=@var{filename} ] | |
| 1010 [ -d @var{directory} | --directory=@var{directory} ] | |
| 1011 @end smallexample | |
| 1012 | |
| 1013 One of @samp{-q} or @samp{-r} (or their longer-named counterparts) must | |
| 1014 be present upon each call to @code{queue-pr}. These options provide | |
| 1015 different functions, as described below. | |
| 1016 | |
| 1017 @table @code | |
| 1018 @item -q | |
| 1019 @itemx --queue | |
| 1020 Accepts standard input as an incoming mail message, placing this message | |
| 1021 in an incrementally numbered file in the @w{@file{gnats-queue}} directory | |
| 1022 under @w{@code{@var{GNATS_ROOT}}} (@pxref{Locations,,Where @sc{gnats} | |
| 1023 lives}). | |
| 1024 | |
| 1025 @item -r | |
| 1026 @itemx --run | |
| 1027 Redirects files in the @file{gnats-queue} directory into the program | |
| 1028 @code{file-pr} one by one. | |
| 1029 | |
| 1030 @item -f @var{filename} | |
| 1031 @itemx --file=@var{filename} | |
| 1032 Used with @samp{-q} (or @samp{--queue}), accepts the file denoted by | |
| 1033 @var{filename} as input rather than reading from standard input. | |
| 1034 | |
| 1035 @item -d @var{directory} | |
| 1036 @itemx --directory=@var{directory} | |
| 1037 Resets the default @var{directory} value, which is by default | |
| 1038 @w{@file{@var{GNATS_ROOT}/gnats-queue}}. When @w{@samp{-d | |
| 1039 @var{directory}}} is used in conjunction with the @samp{-q} (or | |
| 1040 @samp{--queue}) option, @w{@code{queue-pr}} files incoming messages into | |
| 1041 @var{directory} rather than the @file{gnats-queue} directory. When | |
| 1042 @w{@samp{-d @var{directory}}} is used in conjunction with the @samp{-r} | |
| 1043 (or @samp{--run}) option, @code{queue-pr} redirects into | |
| 1044 @w{@code{file-pr}} files from @var{directory} rather than from the | |
| 1045 @w{@file{gnats-queue}} directory. | |
| 1046 @end table | |
| 1047 | |
| 1048 @node file-pr | |
| 1049 @subsection Processing incoming traffic | |
| 1050 @cindex @code{file-pr} | |
| 1051 @cindex processing incoming traffic | |
| 1052 | |
| 1053 @code{queue-pr} hands off queued Problem Reports to @code{file-pr} one | |
| 1054 at a time. @code{file-pr} checks each Problem Report for correct | |
| 1055 information in its fields (particularly a correct @samp{>Category:}), | |
| 1056 assigns it an identification number, and files it in the database under | |
| 1057 the appropriate category. | |
| 1058 | |
| 1059 If the @samp{>Category:} field does not contain a valid category value | |
| 1060 (i.e., matching a line in the @code{categories} file; | |
| 1061 @pxref{categories,,The @code{categories} file}), the PR is given a | |
| 1062 @samp{>Category:} value of @samp{pending} and is placed in the | |
| 1063 @file{pending} directory. The @sc{gnats} administrator is notified of | |
| 1064 the unplaceable PR. | |
| 1065 | |
| 1066 @code{file-pr} assigns the Problem Report an identification number, | |
| 1067 files it in the @sc{gnats} database (under @w{@samp{pending}}, if the | |
| 1068 @samp{>Category:} field contains an invalid category), and sends | |
| 1069 acknowledgements to appropriate parties. The person responsible for | |
| 1070 that category of problem (@pxref{categories,,The @code{categories} | |
| 1071 file}) and the person responsible for the submitter site where the PR | |
| 1072 originated (@pxref{submitters,,The @code{submitters} file}) receive a | |
| 1073 copy of the PR in its entirety. Optionally, the originator of the PR | |
| 1074 receives an acknowledgement that the PR arrived and was filed | |
| 1075 (@pxref{Local configuration,,Changing your local configuration}). | |
| 1076 | |
| 1077 The usage for @code{file-pr} is as follows: | |
| 1078 | |
| 1079 @smallexample | |
| 1080 file-pr [ -f @var{filename} | --file=@var{filename} ] | |
| 1081 [ -d @var{directory} | --directory=@var{directory}b ] | |
| 1082 [ -D | --debug ] [ -h | --help ] [ -V | --version ] | |
| 1083 @end smallexample | |
| 1084 | |
| 1085 @code{file-pr} requires no options in order to operate, and takes input | |
| 1086 from standard input (normally, the output of @w{@samp{queue-pr -r}}) | |
| 1087 unless otherwise specified. The options include: | |
| 1088 | |
| 1089 @table @code | |
| 1090 @item -f @var{filename} | |
| 1091 @itemx --filename=@var{filename} | |
| 1092 Uses @var{filename} as input rather than standard input. | |
| 1093 | |
| 1094 @item -d @var{directory} | |
| 1095 @itemx --directory=@var{directory} | |
| 1096 Performs refiling operations in @var{directory} rather than in | |
| 1097 @w{@code{@var{GNATS_ROOT}}}. | |
| 1098 | |
| 1099 @item -D | |
| 1100 @itemx --debug | |
| 1101 Give debugging output while @code{file-pr} is running. | |
| 1102 | |
| 1103 @item -h | |
| 1104 @itemx --help | |
| 1105 Prints the usage for @code{file-pr}. | |
| 1106 | |
| 1107 @item -V | |
| 1108 @itemx --version | |
| 1109 Prints the version number for @code{file-pr}. | |
| 1110 @end table | |
| 1111 | |
| 1112 @node at-pr | |
| 1113 @subsection Timely reminders | |
| 1114 @cindex @code{at-pr} | |
| 1115 @cindex timely reminders | |
| 1116 @cindex automatic notification | |
| 1117 @cindex notification of overdue PRs | |
| 1118 | |
| 1119 @code{at-pr} creates a queued job using @code{at} which, after an | |
| 1120 allotted @dfn{response time} is past, checks the PR to see if its state | |
| 1121 has changed from @samp{open}. | |
| 1122 | |
| 1123 The @file{submitters} file contains the response time for each | |
| 1124 @w{@code{>Submitter-Id:}} (@pxref{submitters,,The @code{submitters} file}). | |
| 1125 The time is determined in @dfn{business hours}, which are defined by | |
| 1126 default as 8:00am to 5:00pm Monday through Friday, local time. These | |
| 1127 hours are defined in the @file{config} file (@pxref{config,,The | |
| 1128 @code{config} file}). | |
| 1129 | |
| 1130 If the PR is still open after the requisite time period has passed, | |
| 1131 @code{at-pr} sends a reminder to the @sc{gnats} administrator, to the | |
| 1132 maintainer responsible for that submitter, and to the maintainer | |
| 1133 responsible for the PR with the following message: | |
| 1134 | |
| 1135 @cindex reminder message | |
| 1136 @cindex @code{at-pr} | |
| 1137 @smallexample | |
| 1138 To: @var{submitter-contact} @var{responsible} @var{gnats-admin} | |
| 1139 Subject: PR @var{gnats-id} not analyzed in @var{#hours} hours | |
| 1140 | |
| 1141 PR @var{gnats-id} was not analyzed within the acknowledgment period | |
| 1142 of @var{#hours} business hours. The pertinent information is: | |
| 1143 | |
| 1144 Submitter-Id: @var{submitter} | |
| 1145 Originator: @var{full name of the submitter} | |
| 1146 Synopsis: @var{synopsis} | |
| 1147 Person responsible for the PR: @var{responsible} | |
| 1148 | |
| 1149 -- | |
| 1150 The GNU Problem Report Management System (GNATS) | |
| 1151 @end smallexample | |
| 1152 | |
| 1153 @node pr-edit | |
| 1154 @subsection The @code{edit-pr} driver | |
| 1155 @cindex @code{pr-edit} | |
| 1156 @cindex @code{edit-pr} driver | |
| 1157 @cindex driver for @code{edit-pr} | |
| 1158 | |
| 1159 @code{pr-edit} does the background work for @code{edit-pr}, including | |
| 1160 error-checking and refiling newly edited Problem Reports and handling | |
| 1161 file locks. It can be called interactively, though it has no useable | |
| 1162 editing interface. | |
| 1163 | |
| 1164 The usage for @code{pr-edit} is: | |
| 1165 | |
| 1166 @smallexample | |
| 1167 pr-edit [ -l @var{maintainer} --lock=@var{maintainer} ] | |
| 1168 [ -u | --unlock ] [ -c | --check ] [ -F ] | |
| 1169 [ -L | --lockdb ] [ -U | --unlockdb ] | |
| 1170 [ -f @var{filename} | --filename=@var{filename} ] | |
| 1171 [ -d @var{directory} | --directory=@var{directory} ] | |
| 1172 [ -h | --help ] [ -V | --version ] | |
| 1173 [ @var{gnats-id} ] | |
| 1174 @end smallexample | |
| 1175 | |
| 1176 @cindex PR locks | |
| 1177 @cindex locks | |
| 1178 A @dfn{lock} is placed on a Problem Report while the PR is being edited. | |
| 1179 The lock is simply a file in the same directory as the PR, with the name | |
| 1180 @w{@file{@var{gnats-id}.lock}}, which contains the name of the maintainer | |
| 1181 who created the lock. @var{maintainer} then ``owns'' the lock, and must | |
| 1182 remove it before the PR can be locked again, even by the same | |
| 1183 @var{maintainer}@footnote{This approach may seem heavy-handed, but it | |
| 1184 ensures that changes are not overwritten.}. If a PR is already locked | |
| 1185 when you attempt to edit it, @code{pr-edit} prints an error message | |
| 1186 giving the name of the maintainer who is currently editing the PR. | |
| 1187 | |
| 1188 If you do not specify @w{@var{gnats-id}}, @code{pr-edit} reads from | |
| 1189 standard input. You must specify @w{@var{gnats-id}} for the functions | |
| 1190 which affect PR locks, @samp{--lock=@var{maintainer}} and | |
| 1191 @samp{--unlock}. | |
| 1192 | |
| 1193 @table @code | |
| 1194 @item -l @var{maintainer} | |
| 1195 @itemx --lock=@var{maintainer} | |
| 1196 Locks Problem Report @w{@var{gnats-id}}, failing (and returning an error | |
| 1197 message) if @w{@var{gnats-id}} is already locked, or if @w{@var{gnats-id}} | |
| 1198 does not exist. @code{pr-edit} requires that you specify | |
| 1199 @w{@var{gnats-id}} when using this option. | |
| 1200 | |
| 1201 @item -u | |
| 1202 @itemx --unlock | |
| 1203 Unlocks Problem Report @w{@var{gnats-id}}. @code{pr-edit} requires that | |
| 1204 you specify @w{@var{gnats-id}} when using this option. You must own a | |
| 1205 file lock to remove it. | |
| 1206 | |
| 1207 @item -L | |
| 1208 @itemx --lockdb | |
| 1209 Locks the GNATS database as a whole. This will prevent any modification | |
| 1210 to any part of the system while it's locked. | |
| 1211 | |
| 1212 @item -U | |
| 1213 @itemx --unlockdb | |
| 1214 Unlocks the GNATS database as a whole, allowing modification of its | |
| 1215 files. | |
| 1216 | |
| 1217 @item -c | |
| 1218 @itemx --check | |
| 1219 Checks the Problem Report in @w{@var{gnats-id}} (or standard input, if | |
| 1220 @w{@var{gnats-id}} is not present) for correct information in its | |
| 1221 @w{@sc{Enumerated}} fields. @code{pr-edit} complains about any bogus | |
| 1222 information in the Problem Report. | |
| 1223 | |
| 1224 @item -F | |
| 1225 Forces the PR to be submitted to the database, even if there is no | |
| 1226 current index entry for it (i.e., even if the PR did not exist in the | |
| 1227 database previously). | |
| 1228 | |
| 1229 @emph{Warning: using this option may corrupt your index.} If you use | |
| 1230 it, be sure you know what you are doing. | |
| 1231 | |
| 1232 @item -f @var{filename} | |
| 1233 @itemx --filename=@var{filename} | |
| 1234 Reads @var{filename} rather than standard input. | |
| 1235 | |
| 1236 @item -d @var{directory} | |
| 1237 @itemx --directory=@var{directory} | |
| 1238 Resets the operating directory (@w{@code{@var{GNATS_ROOT}}}). | |
| 1239 | |
| 1240 @item -h | |
| 1241 @itemx --help | |
| 1242 Prints the usage for @code{pr-edit}. | |
| 1243 | |
| 1244 @item -V | |
| 1245 @itemx --version | |
| 1246 Prints the version number for @code{pr-edit}. | |
| 1247 @end table | |
| 1248 @node pr-addr | |
| 1249 @subsection Address retrieval | |
| 1250 @cindex address retrieval | |
| 1251 @cindex @code{pr-addr} | |
| 1252 | |
| 1253 Returns an electronic mail address when given a valid @dfn{nametag}, as | |
| 1254 it appears in the @file{responsible} file (@pxref{responsible,,The | |
| 1255 @code{responsible} file}). If @var{nametag} is not valid, @code{pr-addr} | |
| 1256 will tell the user that it could not find the requested address. | |
| 1257 | |
| 1258 Usage is simply: | |
| 1259 | |
| 1260 @smallexample | |
| 1261 pr-addr @var{name} | |
| 1262 @end smallexample |