Mercurial > bitten > bitten-test
annotate doc/upgrade.txt @ 899:6ac02ad71cc4
Update ChangeLog before 0.6 release.
author | hodgestar |
---|---|
date | Fri, 11 Mar 2011 11:10:41 +0000 |
parents | 95696a84e1fa |
children |
rev | line source |
---|---|
850 | 1 .. -*- mode: rst; encoding: utf-8 -*- |
2 | |
3 ========= | |
4 Upgrading | |
5 ========= | |
6 | |
7 .. contents:: Contents | |
867
95696a84e1fa
Change upgrade documentation contents depth to 1 to exclude the schema version list.
hodgestar
parents:
859
diff
changeset
|
8 :depth: 1 |
850 | 9 .. sectnum:: |
10 | |
11 | |
857
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
12 Bitten's database schema is versioned using the `bitten_version` entry in |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
13 Trac's system table. If you install a version of Bitten with a more recent |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
14 schema you will need to run `trac-admin update` after installing Bitten to |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
15 update your database. Until this done Trac will not activate your new |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
16 Bitten installation. |
850 | 17 |
18 .. note:: | |
19 | |
857
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
20 You should back up your Trac database and Trac environment before running |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
21 `trac-admin upgrade`. |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
22 |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
23 .. note:: |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
24 |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
25 If you are using a SQLite database file, Trac automatically creates a copy |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
26 before proceeding with the update. This should not be relied upon but can |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
27 be useful if you have ignored the advice above. |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
28 |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
29 Bitten's upgrade scripts attempt to commit changes made to the database each |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
30 time a new schema version is reached. This ensures that if an upgrade fails |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
31 to complete the Bitten database is left in the most up-to-date state possible. |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
32 |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
33 For example, if you were upgrading from Bitten schema 6 to schema version 12 |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
34 and duplicate builds were found during the attempt to upgrade to schema 10, your |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
35 database would be left at schema 9. |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
36 |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
37 |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
38 Removing Duplicate Builds |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
39 ========================= |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
40 |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
41 Bitten schema version 10 adds a unique index on the columns |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
42 `(config, platform, rev)` to the `bitten_build` table. This constraint is |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
43 relied on by Bitten but was not enforced in earlier versions and duplicate |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
44 builds could arise. Before the upgrade to schema version 10 can complete, these |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
45 duplicate builds must be removed. The `trac-admin upgrade` will produce a list |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
46 of duplicates but the decision on which to keep remains with the user. |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
47 |
859 | 48 A script_ for removing builds is provided. This scripts supports schema |
857
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
49 versions 9 through 12. |
fc9955ec8c67
Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents:
850
diff
changeset
|
50 |
859 | 51 .. _script: http://bitten.edgewall.org/browser/trunk/contrib/deletebuild.py |
850 | 52 |
53 | |
858
ae7022ade5cc
Add documentation section on reporting upgrade issues.
hodgestar
parents:
857
diff
changeset
|
54 Reporting Upgrade Issues |
ae7022ade5cc
Add documentation section on reporting upgrade issues.
hodgestar
parents:
857
diff
changeset
|
55 ======================== |
ae7022ade5cc
Add documentation section on reporting upgrade issues.
hodgestar
parents:
857
diff
changeset
|
56 |
ae7022ade5cc
Add documentation section on reporting upgrade issues.
hodgestar
parents:
857
diff
changeset
|
57 Debugging upgrade issues can be difficult since the Bitten development team |
ae7022ade5cc
Add documentation section on reporting upgrade issues.
hodgestar
parents:
857
diff
changeset
|
58 does not have access to your database. Attaching a description of your |
ae7022ade5cc
Add documentation section on reporting upgrade issues.
hodgestar
parents:
857
diff
changeset
|
59 database schema before and after running `trac-admin upgrade` to your |
ae7022ade5cc
Add documentation section on reporting upgrade issues.
hodgestar
parents:
857
diff
changeset
|
60 request for assistance may help others diagnose the problem more swiftly. |
ae7022ade5cc
Add documentation section on reporting upgrade issues.
hodgestar
parents:
857
diff
changeset
|
61 |
ae7022ade5cc
Add documentation section on reporting upgrade issues.
hodgestar
parents:
857
diff
changeset
|
62 You can create such a schema description using Gerald_ or a similar tool. |
ae7022ade5cc
Add documentation section on reporting upgrade issues.
hodgestar
parents:
857
diff
changeset
|
63 |
859 | 64 .. _gerald: http://pypi.python.org/pypi/gerald |
858
ae7022ade5cc
Add documentation section on reporting upgrade issues.
hodgestar
parents:
857
diff
changeset
|
65 |
ae7022ade5cc
Add documentation section on reporting upgrade issues.
hodgestar
parents:
857
diff
changeset
|
66 |
850 | 67 Upgrade history |
68 =============== | |
69 | |
70 The current version of the Bitten schema is version 12. | |
71 | |
72 Version 12 | |
73 ---------- | |
74 | |
75 * `last activity` column added to `bitten_build`. | |
76 | |
77 Version 11 | |
78 ---------- | |
79 | |
80 * Badly named log level files that ended with `.log.level` created by earlier | |
81 versions of Bitten were renamed to end in `.log.levels` which is the correct | |
82 extension. | |
83 | |
84 * Log level files that had not been correctly deleted by earlier versions of | |
85 Bitten were cleaned up. | |
86 | |
87 Version 10 | |
88 ---------- | |
89 | |
90 * PostgreSQL sequences on the `id` column that had not been correctly updated | |
91 by previous Bitten upgrade scripts were corrected. This affected four tables: | |
92 `bitten_build`, `bitten_log`, `bitten_platform` and `bitten_report`. | |
93 | |
94 * A unique index on the columns `(config, platform, rev)` was added to the | |
95 `bitten_build` table and an old unique index on `(config, rev, slave)` was | |
96 removed. | |
97 | |
98 .. note:: | |
99 | |
100 The lack of an index on `(config, platform, rev)` in ealier versions of | |
101 Bitten allowed duplicate builds to be created in the database under some | |
102 conditions. These duplicate builds need to be manually removed before the | |
103 upgrade to version 10 can complete. | |
104 | |
105 Version 9 | |
106 --------- | |
107 | |
108 * The `id` column of the `bitten_rule` table was converted from a text column | |
109 to an integer one. | |
110 | |
111 Version 8 | |
112 --------- | |
113 | |
114 * Log messages that had been stored in the `bitten_log_messages` table were | |
115 migrated to files. | |
116 | |
117 * A `filename` field was added to the `bitten_log` table to record the | |
118 location of the new log files. | |
119 | |
120 Version 7 | |
121 --------- | |
122 | |
123 * The `bitten_error` table as added to record the reasons for step failures. | |
124 | |
125 Version 6 | |
126 --------- | |
127 | |
128 * Filenames stored in the `value` column of `bitten_report_item` where | |
129 normalized to use `/` as the path separator. | |
130 | |
131 * The `generator` columns in `bitten_log` and `bitten_report` previously | |
132 stored just the short tag name of the associated generator. These were | |
133 updated to store the full tag name of the generator (including the XML | |
134 namespace). For example, `pipe` was changed to | |
135 `http://bitten.edgewall.org/tools/sh#pipe`. | |
136 | |
137 Version 5 | |
138 --------- | |
139 | |
140 * An `orderno` column was added to the `bitten_log` table to record the | |
141 order in which sets of log messages were generated. | |
142 | |
143 * The `bitten_report` and `bitten_report_item` tables were added to record | |
144 reports generated by unit tests and other build tools. | |
145 | |
146 * Report data was imported from the old Berkeley DB XML store into the new | |
147 database tables. | |
148 | |
149 Version 4 | |
150 --------- | |
151 | |
152 * The build configuration that generated a report was added to the report | |
153 metadata in the Berkeley DB XML store. | |
154 | |
155 Version 3 | |
156 --------- | |
157 | |
158 * The `recipe` column was added to `bitten_config` to store the recipe XML. | |
159 | |
160 Version 2 | |
161 --------- | |
162 | |
163 * The `bitten_log` and `bitten_log_message` tables were created for storing | |
164 log messages. | |
165 | |
166 * The `log` column was removed from `bitten_step` and the log messages where | |
167 migrated to the two new logging tables. | |
168 | |
169 Version 1 | |
170 --------- | |
171 | |
172 * The first Bitten database schema. |