new file mode 100644
--- /dev/null
+++ b/doc/upgrade.txt
@@ -0,0 +1,131 @@
+.. -*- mode: rst; encoding: utf-8 -*-
+
+=========
+Upgrading
+=========
+
+.. contents:: Contents
+   :depth: 2
+.. sectnum::
+
+
+.. note::
+
+   TODO: Outline upgrade procedure, including committing of upgrades after
+   each step.
+      
+
+Manually Removing Builds
+========================
+
+.. note::
+
+   TODO: Write this section
+
+
+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.