             Upgrading a GNATS 3 installation to GNATS 4

NOTE: This document is in a preliminary state.  The procedures
described herein are believed to work, but are not fully tested.
People upgrading according to these procedures are doing so entirely
on their own risk.  You have been warned!

This document covers upgrading from a reasonably new GNATS 3.1xx
installation to GNATS 4.  If your installation is older than circa
version 3.109, you need to review the UPGRADING.old file before
carrying out the steps detailed here.


Overview
========

Although almost all of the GNATS internals have been redesigned and
rewritten for GNATS 4, little has changed in the format and structure
of the database data.  The only change that needs to be taken into
account when upgrading is the fact that the database index format is
binary in a default installation of GNATS 4.  Thus, you will need to
regenerate your database index by using the gen-index tool.

Apart from building and installing new binaries, the major changes
which impinge on the upgrade procedure are all on the configuration
side.  The main database configuration file, dbconfig, is far more
complex and powerful than the old config file, and while the
installation process creates a sensible set of default values which
are similar to GNATS 3.11x's defaults, you still need to migrate any
changes you may have made to your own local configuration.

Another aspect which needs consideration are remote submitter sites.
Such sites either need to be instructed to upgrade their locally
installed copies of the GNATS user tools (send-pr, edit-pr and
query-pr), or they should be given access through interfaces such as
Gnatsweb.

Since the GNATS network daemon has been completely reworked, with an
entirely new command set, all network-based interfaces, such as
Gnatsweb and TkGnats need to be upgraded to versions that support
GNATS 4.  Currently, Gnatsweb is the only network-based interface
which has been rewritten for GNATS 4.  The contrib directory of this
distribution contains some third-party interfaces, and the README file
contains pointers to where one can obtain the newest versions of these
tools.

This document only deals with upgrading GNATS itself.  Third-party
tools should have separate upgrading instructions in their
distributions.


Upgrading
=========

1. Before you begin, make a backup of your entire GNATS database
   directory hierarchy, the GNATS executables directory and the GNATS
   user tools (send-pr, query-pr etc.)  The locations of these may
   vary, but in a default GNATS 3 installation, the database(s) reside
   under /usr/local/share/gnats, the executables are located in
   /usr/local/libexec/gnats and the user tools reside in
   /usr/local/bin.

2. (optional) In order to avoid confusing your users, you may want to
   remove the old GNATS 3 executables and tools, escpecially if you
   plan to install GNATS 4 in a different location than version 3.

3. Build and install GNATS 4.  See the INSTALL file and the GNATS
   manual for details.  It is recommended that you use the
   --with-gnats-default-db option when running configure, in order to
   set the default database to be one of your already existing GNATS 3
   databases.

4. Edit the GNATS `databases' file, located in SYSCONFDIR/gnats.  In a
   default GNATS 4 installation this is /usr/local/etc/gnats.  Add
   entries for all your old GNATS 3 databases.

5. In GNATS 3, the file gnatsd.conf specifies minimum access levels
   for the different hosts accessing the GNATS daemon, gnatsd.  There
   is one gnatsd.conf for each database.  In GNATS 4, these files have
   been replaced by a single file named gnatsd.host_access which
   contains settings that apply across all the databases on the
   server.  This file is located in the same directory as the
   `databases' file.  You need to combine the host access settings
   from all your GNATS 3 databases and add them to the
   gnatsd.host_access file.  Note that you are no longer able to
   control host access on a per-database basis.  Optionally, you may
   delete the old gnatsd.conf files.

6. Next, you need to migrate the settings in the old `config' files of
   your databases to corresponding `dbconfig' files.  The database you
   specified with the --with-gnats-default-db configure option got a
   default `dbconfig' installed.  This default file contains field
   definitions etc. which makes this version of GNATS behave almost
   exactly like older versions.  Copy this default file to the
   gnats-adm directories of any other GNATS databases that you may
   have on your host before you proceed to migrate your old config
   settings.

   The following is a list of the configuration directives that may be
   present in a `config' file and their counterparts (if any) in GNATS
   4.

    GNATS_ADDR
        This setting has no counterpart in GNATS 4, since GNATS no
        longer needs to know its own mail address.

    GNATS_ADMIN
        This setting is now set in the `responsible' file in the
        gnats-adm directory of your database(s).

    GNATS_SITE
        GNATS 4 has no concept of a named `site', so this directive is
        obsolete.

    SUBMITTER
        Obsolete, since it relates to GNATS_SITE.

    DEFAULT_RELEASE
    DEFAULT_ORGANIZATION
        The GNATS 4 `dbconfig' file has separate configuration
        sections for each defined field.  Field defaults are set with
        the "default" keyword in these sections.  See the treatment of
        the `dbconfig' file in the GNATS 4 manual for details.

    NOTIFY
        Controlled by the "notify-about-expired-prs" setting in the
        `dbconfig' file.

    ACKNOWLEDGE
        Controlled by the "send-submitter-ack" setting in the
        `dbconfig' file.

    DEFAULT_SUBMITTER
        The default submitter is now always the first entry in the
        `submitters' file of your database.

    KEEP_RECEIVED_HEADERS
        Controlled by the "keep-all-received-headers" setting in the
        `dbconfig' file.

    DEBUG_MODE
        Controlled by the "debug-mode" setting in the `dbconfig' file.

    BDAY_START
    BDAY_END
    BWEEK_START
    BWEEK_END
        Controlled by the settings "business-day-hours" and
        "business-week-days" in the `dbconfig' file.

    DEFINE_CATEGORY
        The default category for PRs that arrive without one is the
        first category listed in the `categories' file of your
        database.

   See the section on the dbconfig file in the GNATS manual, chapter 4
   for details.  After your are done migrating the settings, you may
   optionally delete the old config files.  Since there are many more
   configuration settings available in the GNATS 4 `dbconfig' file,
   you should take some time to review them all before proceeding.

7. GNATS 4 uses a different password format in the gnatsd.access file
   than older versions since it supports crypt() and MD5 passwords
   (see the GNATS manual, Appendix C, "Controlling access to
   databases" for details.)  You need to translate your old
   gnatsd.access files to the new format by using the gnats-pwconv
   tool which was installed in the EXEC-PREFIX/libexec/gnats
   directory, typically /usr/local/libexec/gnats.  See "Administrative
   utilities" in Chapter 4 of the GNATS manual for details on how to
   use gnats-pwconv.

8. The final step involves regenerating the indexes of your databases.
   For this, log in as the user `gnats'.  Then run the gen-index
   command for each of your databases.  See "Administrative utilities"
   in Chapter 4 of the GNATS manual for details on how to use
   gen-index.

9. Sit back and enjoy your new GNATS 4 setup...
