# HG changeset patch # User hodgestar # Date 1287402738 0 # Node ID 242f2e225c4e3795ec52ae90d935fcadc8452b5a # Parent a08acf72a846630e1d18a3307568bde6471a98d9 0.6dev: Merged [928,935:937,943:945] from trunk. diff --git a/doc/index.txt b/doc/index.txt --- a/doc/index.txt +++ b/doc/index.txt @@ -26,5 +26,6 @@ * `Build Links `_ * `Notification `_ * `Report Formats `_ + * `Upgrading Bitten `_ * `Generated API Documentation `_ - \ No newline at end of file + diff --git a/doc/upgrade.txt b/doc/upgrade.txt 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.