Changes to gnats/doc/gnats-faq.texi

[Hans-Albert Schneider]

Index: gnats/doc/gnats-faq.texi
diff -c gnats/doc/gnats-faq.texi:1.4 gnats/doc/gnats-faq.texi:1.5
*** gnats/doc/gnats-faq.texi:1.4        Fri Mar  8 14:28:30 2002
--- gnats/doc/gnats-faq.texi    Fri Mar  8 17:30:48 2002
***************
*** 323,332 ****
  
  @menu
  * Add a database::              How to create a new database
  @end menu
  
! @node Add a database,  , General configuration, General configuration
! @comment  node-name,  next,  previous,  up
  @subsubheading How do I add a new database?
  
  @noindent
--- 323,333 ----
  
  @menu
  * Add a database::              How to create a new database
+ * Renaming a Category::         
  @end menu
  
! @node Add a database, , General configuration, General
! configuration @comment node-name, next, previous, up
  @subsubheading How do I add a new database?
  
  @noindent
***************
*** 353,364 ****
  used when no category is given in a report, and when a report names an
  invalid category.
  
  @item
  As the @sc{gnats} user, 
  run @samp{mkcat --directory=/usr/local/gnats/db2} to create the
! directories for the categories, and maybe
! @samp{gen-index --directory=/usr/local/gnats/db2} to create an
! (empty) index file.
  
  @item
  Now add a line for the new database to @address@hidden, like
--- 354,385 ----
  used when no category is given in a report, and when a report names an
  invalid category.
  
+ Also note that each database needs its own mail address for submissions
+ (see also step 8 below), and that you must enter it in the file
+ @file{config}.
+ 
  @item
  As the @sc{gnats} user, 
  run @samp{mkcat --directory=/usr/local/gnats/db2} to create the
! directories for the categories.  Remove the files @file{current} and
! @file{index}, if they exist.
! 
! @item
! If the new database is split off of another one, move or copy the
! existing reports to their new location.  This is easiest if the
! categories have the same names as in the original database.  (See
! @ref{Renaming a Category} if some of them changed names.)
! 
! Run the program @code{gen-index} to create the index file
! (@pxref{gen-index,,Regenerating the index,gnats,Keeping Track}).
! 
! Find the greatest report number and put it (or any larger number)
! into @file{/usr/local/gnats/db2/gnats-adm/current}.
! 
! @strong{Caution:} E-mail updates to the PRs you moved to the new
! database may still arrive at the old database.  You may want to
! contact everybody who knows about these PRs, asking them to use
! the mail address of the new database when sending a follow-up.
  
  @item
  Now add a line for the new database to @address@hidden, like
***************
*** 388,393 ****
--- 409,425 ----
  GreatNewDB-bugs:  "|/usr/local/lib/gnats/queue-pr -d /usr/local/gnats/db2 -q"
  GreatNewDB-query: "|/usr/local/lib/gnats/mail-query -d /usr/local/gnats/db2"
  @end smallexample
+ 
+ Make sure that @file{/usr/local/gnats/db2/gnats-adm/config} gives the
+ correct mail addresses for @var{GNATS_ADDR} (this @emph{must} be
+ different for each database) and for @var{GNATS_ADMIN} (this is probably
+ the same for all databases).
+ 
+ @smallexample
+ GNATS_ADDR="GreatNewDB-bugs@@bugs.example.com"
+ GNATS_ADMIN="gnats-admin@@bugs.example.com"
+ @end smallexample
+ 
  @end enumerate
  
  @noindent
***************
*** 442,447 ****
--- 474,516 ----
  
  @end enumerate
  
+ 
+ @node Renaming a Category
+ @comment  node-name,  next,  previous,  up
+ @subsubheading How do I rename a category?
+ 
+ Renaming a category requires to touch every PR in that category,
+ because each report contains the name of its category.
+ 
+ To rename category @code{A} to @code{B}, proceed as follows:
+ 
+ @enumerate
+ @item
+ Create a new category @code{B}.
+ 
+ @item
+ Edit every report in category @code{A}, changing its category to
+ @code{B}.
+ This can be done with any @sc{gnats} client; check the archives
+ of the @sc{help-gnats} mailing list for hints about automating
+ this step.
+ 
+ @item
+ Run @code{gen-index} (@pxref{gen-index,,Regenerating the
+ index,gnats,Keeping Track}) to refresh the @file{index} file.
+ 
+ @item
+ If you are using @sc{gnats} 4 (or planning to upgrade soon), you
+ should not remove the category @code{A}.  When a follow-up to an
+ existing PR arrives via e-mail, @sc{gnats} 4.x checks that both
+ the category and the PR number indicated in the mail exist (this
+ is a sanity check).
+ 
+ To reduce the risk of new reports being filed to category
+ @code{A}, change its description in the @file{categories} file to
+ something like @samp{obsolete, use category @code{B} instead}.
+ 
+ @end enumerate
  
  
  @node Gnatsd