--- a/doc/index.txt
+++ b/doc/index.txt
@@ -26,5 +26,6 @@
  * `Build Links <links.html>`_
  * `Notification <notify.html>`_
  * `Report Formats <reports.html>`_
+ * `Upgrading Bitten <upgrade.html>`_
  * `Generated API Documentation <api/index.html>`_
- 
\ No newline at end of file
+ 

new file mode 100644
--- /dev/null
+++ b/doc/upgrade.txt
@@ -0,0 +1,172 @@
+.. -*- mode: rst; encoding: utf-8 -*-
+
+=========
+Upgrading
+=========
+
+.. contents:: Contents
+   :depth: 1
+.. sectnum::
+
+
+Bitten's database schema is versioned using the `bitten_version` entry in
+Trac's system table. If you install a version of Bitten with a more recent
+schema you will need to run `trac-admin update` after installing Bitten to
+update your database. Until this done Trac will not activate your new
+Bitten installation.
+
+.. note::
+
+   You should back up your Trac database and Trac environment before running
+   `trac-admin upgrade`.
+
+.. note::
+
+   If you are using a SQLite database file, Trac automatically creates a copy
+   before proceeding with the update. This should not be relied upon but can
+   be useful if you have ignored the advice above.
+
+Bitten's upgrade scripts attempt to commit changes made to the database each
+time a new schema version is reached. This ensures that if an upgrade fails
+to complete the Bitten database is left in the most up-to-date state possible.
+
+For example, if you were upgrading from Bitten schema 6 to schema version 12
+and duplicate builds were found during the attempt to upgrade to schema 10, your
+database would be left at schema 9.
+      
+
+Removing Duplicate Builds
+=========================
+
+Bitten schema version 10 adds a unique index on the columns
+`(config, platform, rev)` to the `bitten_build` table. This constraint is
+relied on by Bitten but was not enforced in earlier versions and duplicate
+builds could arise. Before the upgrade to schema version 10 can complete, these
+duplicate builds must be removed. The `trac-admin upgrade` will produce a list
+of duplicates but the decision on which to keep remains with the user.
+
+A script_ for removing builds is provided. This scripts supports schema
+versions 9 through 12.
+
+.. _script: http://bitten.edgewall.org/browser/trunk/contrib/deletebuild.py
+
+
+Reporting Upgrade Issues
+========================
+
+Debugging upgrade issues can be difficult since the Bitten development team
+does not have access to your database.  Attaching a description of your
+database schema before and after running `trac-admin upgrade` to your
+request for assistance may help others diagnose the problem more swiftly.
+
+You can create such a schema description using Gerald_ or a similar tool.
+
+.. _gerald: http://pypi.python.org/pypi/gerald
+
+
+Upgrade history
+===============
+
+The current version of the Bitten schema is version 12.
+
+Version 12
+----------
+
+* `last activity` column added to `bitten_build`.
+
+Version 11
+----------
+
+* Badly named log level files that ended with `.log.level` created by earlier
+  versions of Bitten were renamed to end in `.log.levels` which is the correct
+  extension.
+
+* Log level files that had not been correctly deleted by earlier versions of
+  Bitten were cleaned up.
+
+Version 10
+----------
+
+* PostgreSQL sequences on the `id` column that had not been correctly updated
+  by previous Bitten upgrade scripts were corrected. This affected four tables:
+  `bitten_build`, `bitten_log`, `bitten_platform` and `bitten_report`.
+
+* A unique index on the columns `(config, platform, rev)` was added to the
+  `bitten_build` table and an old unique index on `(config, rev, slave)` was
+  removed.
+
+.. note::
+
+  The lack of an index on `(config, platform, rev)` in ealier versions of
+  Bitten allowed duplicate builds to be created in the database under some
+  conditions. These duplicate builds need to be manually removed before the
+  upgrade to version 10 can complete. 
+   
+Version 9
+---------
+
+* The `id` column of the `bitten_rule` table was converted from a text column
+  to an integer one.
+
+Version 8
+---------
+
+* Log messages that had been stored in the `bitten_log_messages` table were
+  migrated to files.
+
+* A `filename` field was added to the `bitten_log` table to record the
+  location of the new log files.
+
+Version 7
+---------
+
+* The `bitten_error` table as added to record the reasons for step failures.
+
+Version 6
+---------
+
+* Filenames stored in the `value` column of `bitten_report_item` where
+  normalized to use `/` as the path separator.
+
+* The `generator` columns in `bitten_log` and `bitten_report` previously
+  stored just the short tag name of the associated generator. These were
+  updated to store the full tag name of the generator (including the XML
+  namespace). For example, `pipe` was changed to
+  `http://bitten.edgewall.org/tools/sh#pipe`.
+
+Version 5
+---------
+
+* An `orderno` column was added to the `bitten_log` table to record the
+  order in which sets of log messages were generated.
+
+* The `bitten_report` and `bitten_report_item` tables were added to record
+  reports generated by unit tests and other build tools.
+
+* Report data was imported from the old Berkeley DB XML store into the new
+  database tables.
+
+Version 4
+---------
+
+* The build configuration that generated a report was added to the report
+  metadata in the Berkeley DB XML store.
+
+Version 3
+---------
+
+* The `recipe` column was added to `bitten_config` to store the recipe XML.
+
+Version 2
+---------
+
+* The `bitten_log` and `bitten_log_message` tables were created for storing
+  log messages.
+   
+* The `log` column was removed from `bitten_step` and the log messages where
+  migrated to the two new logging tables.
+
+Version 1
+---------
+
+* The first Bitten database schema.