--- a/doc/upgrading.txt	Tue Sep 10 00:11:50 2002 +0000
+++ b/doc/upgrading.txt	Tue Sep 10 00:15:59 2002 +0000
@@ -2,7 +2,7 @@
 Upgrading to newer versions of Roundup
 ======================================
 
-Please read each section carefully and edit your instance home files
+Please read each section carefully and edit your tracker home files
 accordingly.
 
 .. contents::
@@ -24,18 +24,38 @@
    define your own Permissions that may be checked in CGI transactions.
 4. Journalling has been made less storage-hungry, so has been turned on
    by default *except* for author, recipient and nosy link/unlink events. You
-   are advised to turn it off in your instances too.
-5. Because of the above changes, the instance configuration has seen some
+   are advised to turn it off in your trackers too.
+5. We've changed the terminology from "instance" to "tracker", to ease the
+   learning curve/impact for new users.
+6. Because of the above changes, the tracker configuration has seen some
    major changes. See below for the details.
 
 Please, *back up your database* before you start the migration process. This
 is as simple as copying the "db" directory and all its contents from your
-instance to somewhere safe.
+tracker to somewhere safe.
 
 
 0.5.0 Configuration
 -------------------
 
+First up, rename your ``instance_config.py`` file to just ``config.py``.
+
+Then edit your tracker's ``__init__.py`` module. It'll currently look
+like this::
+
+ from instance_config import *
+ try:
+     from dbinit import *
+ except ImportError:
+     pass # in installdir (probably :)
+ from interfaces import *
+
+and it needs to be::
+
+ import config
+ from dbinit import open, init
+ from interfaces import Client, MailGW
+
 Due to the new templating having a top-level ``page`` that defines links for
 searching, indexes, adding items etc, the following variables are no longer
 used:
@@ -50,7 +70,7 @@
 - ISSUE_FILTER
 
 The new security implementation will require additions to the dbinit module,
-but also removes the need for the following instance config variables:
+but also removes the need for the following tracker config variables:
 
 - ANONYMOUS_ACCESS
 - ANONYMOUS_REGISTER
@@ -75,7 +95,7 @@
 0.5.0 Database backend changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Your select_db module in your instance has changed a fair bit. Where it used
+Your select_db module in your tracker has changed a fair bit. Where it used
 to contain::
 
  # WARNING: DO NOT EDIT THIS FILE!!!
@@ -89,7 +109,7 @@
 Yes, I realise the irony of the "DO NOT EDIT THIS FILE" statement :)
 Note the addition of the Class, FileClass, IssueClass imports. These are very
 important, as they're going to make the next change work too. You now need to
-modify the top of the dbinit module in your instance from::
+modify the top of the dbinit module in your tracker from::
 
  import instance_config
  from roundup import roundupdb
@@ -109,16 +129,17 @@
      '''
      pass
 
-
+to::
 
-to just::
-
- import instance_config
+ import config
  from select_db import Database, Class, FileClass, IssueClass
 
 Yes, remove the Database and IssueClass definitions and those other imports.
 They're not needed any more!
 
+Look for places in dbinit.py where ``instance_config`` is used too, and
+rename them ``config``.
+
 
 0.5.0 Journalling changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -213,8 +234,8 @@
 4. Roundup checks that users have appropriate Permissions at appropriate times
    (like editing issues).
 
-Your instance dbinit module's *open* function now has to define any
-Permissions that are specific to your instance, and also the assignment
+Your tracker dbinit module's *open* function now has to define any
+Permissions that are specific to your tracker, and also the assignment
 of Permissions to Roles. At the moment, your open function
 ends with::
 
@@ -320,7 +341,7 @@
 and all other users "User". The ``fixroles.py`` script in the tools directory
 will do this. Run it like so (where python is your python 2+ binary)::
 
-  python tools/fixroles.py -i <instance home>
+  python tools/fixroles.py -i <tracker home>
 
 
 
@@ -328,7 +349,7 @@
 ---------------------------
 
 The CGI interface code was completely reorganised and largely rewritten. The
-end result is that this section of your instance interfaces module will need
+end result is that this section of your tracker interfaces module will need
 changing from::
 
  from roundup import mailgw
@@ -358,9 +379,9 @@
 0.5.0 HTML templating
 ---------------------
 
-You'll want to make a backup of your current instance html directory. You
+You'll want to make a backup of your current tracker html directory. You
 should then copy the html directory from the Roundup source template that you
-used to create your instance, and modify it according to your local schema
+used to create your tracker, and modify it according to your local schema
 changes.
 
 If you need help with the new templating system, please ask questions on the
@@ -371,8 +392,8 @@
 0.5.0 Detectors
 ---------------
 
-The nosy reactor has been updated to handle the instance not having an
-"assignedto" property on issues. You may want to copy it into your instance's
+The nosy reactor has been updated to handle the tracker not having an
+"assignedto" property on issues. You may want to copy it into your tracker's
 detectors directory. Chances are you've already fixed it though :)
 
 
@@ -428,7 +449,7 @@
 0.4.2 HTML templating changes
 -----------------------------
 The link() htmltemplate function now has a "showid" option for links and
-multilinks. When true, it only displays the linked node id as the anchor
+multilinks. When true, it only displays the linked item id as the anchor
 text. The link value is displayed as a tooltip using the title anchor
 attribute. To use in eg. the superseder field, have something like this::