Mercurial > bitten > bitten-test

annotate doc/upgrade.txt @ 858:ae7022ade5cc

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation section on reporting upgrade issues.
author hodgestar
date Sun, 17 Oct 2010 22:53:16 +0000
parents fc9955ec8c67
children d9f4c8d7599c
rev   line source
850
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
2
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
3 =========
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
4 Upgrading
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
5 =========
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
6
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
7 .. contents:: Contents
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
8 :depth: 2
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
9 .. sectnum::
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
10
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
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
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
17
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
18 .. note::
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
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
fc9955ec8c67 Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents: 850
diff changeset
48 A script for removing builds is provided [#]_. This scripts supports schema
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
fc9955ec8c67 Documentation on upgrade procedure and how to remove duplicate builds.
hodgestar
parents: 850
diff changeset
51 .. [#] http://bitten.edgewall.org/browser/trunk/contrib/deletebuild.py
850
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
52
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
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
ae7022ade5cc Add documentation section on reporting upgrade issues.
hodgestar
parents: 857
diff changeset
64 .. [gerald] http://pypi.python.org/pypi/gerald
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
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
67 Upgrade history
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
68 ===============
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
69
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
70 The current version of the Bitten schema is version 12.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
71
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
72 Version 12
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
73 ----------
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
74
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
75 * `last activity` column added to `bitten_build`.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
76
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
77 Version 11
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
78 ----------
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
79
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
80 * Badly named log level files that ended with `.log.level` created by earlier
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
81 versions of Bitten were renamed to end in `.log.levels` which is the correct
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
82 extension.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
83
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
84 * Log level files that had not been correctly deleted by earlier versions of
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
85 Bitten were cleaned up.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
86
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
87 Version 10
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
88 ----------
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
89
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
90 * PostgreSQL sequences on the `id` column that had not been correctly updated
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
91 by previous Bitten upgrade scripts were corrected. This affected four tables:
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
92 `bitten_build`, `bitten_log`, `bitten_platform` and `bitten_report`.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
93
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
94 * A unique index on the columns `(config, platform, rev)` was added to the
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
95 `bitten_build` table and an old unique index on `(config, rev, slave)` was
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
96 removed.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
97
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
98 .. note::
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
99
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
100 The lack of an index on `(config, platform, rev)` in ealier versions of
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
101 Bitten allowed duplicate builds to be created in the database under some
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
102 conditions. These duplicate builds need to be manually removed before the
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
103 upgrade to version 10 can complete.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
104
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
105 Version 9
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
106 ---------
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
107
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
108 * The `id` column of the `bitten_rule` table was converted from a text column
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
109 to an integer one.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
110
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
111 Version 8
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
112 ---------
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
113
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
114 * Log messages that had been stored in the `bitten_log_messages` table were
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
115 migrated to files.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
116
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
117 * A `filename` field was added to the `bitten_log` table to record the
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
118 location of the new log files.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
119
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
120 Version 7
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
121 ---------
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
122
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
123 * The `bitten_error` table as added to record the reasons for step failures.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
124
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
125 Version 6
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
126 ---------
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
127
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
128 * Filenames stored in the `value` column of `bitten_report_item` where
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
129 normalized to use `/` as the path separator.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
130
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
131 * The `generator` columns in `bitten_log` and `bitten_report` previously
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
132 stored just the short tag name of the associated generator. These were
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
133 updated to store the full tag name of the generator (including the XML
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
134 namespace). For example, `pipe` was changed to
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
135 `http://bitten.edgewall.org/tools/sh#pipe`.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
136
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
137 Version 5
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
138 ---------
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
139
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
140 * An `orderno` column was added to the `bitten_log` table to record the
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
141 order in which sets of log messages were generated.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
142
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
143 * The `bitten_report` and `bitten_report_item` tables were added to record
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
144 reports generated by unit tests and other build tools.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
145
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
146 * Report data was imported from the old Berkeley DB XML store into the new
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
147 database tables.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
148
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
149 Version 4
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
150 ---------
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
151
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
152 * The build configuration that generated a report was added to the report
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
153 metadata in the Berkeley DB XML store.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
154
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
155 Version 3
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
156 ---------
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
157
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
158 * The `recipe` column was added to `bitten_config` to store the recipe XML.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
159
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
160 Version 2
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
161 ---------
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
162
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
163 * The `bitten_log` and `bitten_log_message` tables were created for storing
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
164 log messages.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
165
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
166 * The `log` column was removed from `bitten_step` and the log messages where
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
167 migrated to the two new logging tables.
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
168
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
169 Version 1
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
170 ---------
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
171
351dfe735924 Add start of upgrade documentation.
hodgestar
parents:
diff changeset
172 * The first Bitten database schema.
Copyright (C) 2012-2017 Edgewall Software