monotone

monotone Mtn Source Tree

Root/UPGRADE

1upgrading monotone to 0.24
2==========================
3
4if you are upgrading from:
5 - 0.23 or earlier: keys are now stored in ~/.monotone/keys (Unix,
6 OS X), or %APPDATA%\Monotone\keys (Windows). You must run 'db
7 migrate' against each of your databases; this will automatically
8 migrate the keys. See NEWS for details.
9 Command line syntax for 'serve' has changed; please adjust startup
10 scripts accordingly.
11 On Windows only, monotone now looks in a different place for the
12 monotonerc file; see NEWS for 0.24 for details.
13 - 0.21 or earlier: hooks governing netsync read permission have
14 changed again; see NEWS for 0.22.
15 - 0.19 or earlier: there are incompatible command line and server
16 configuration changes; see NEWS for 0.20.
17 - 0.18 or earlier: if you have created a ~/.monotonerc, rename it to
18 ~/.monotone/monotonerc, so monotone will still find it.
19 - 0.17: simply make a backup of your databases, just in case, and
20 run "db migrate" on each.
21 - 0.15 or 0.16: see below
22 - 0.14 or earlier: see file README.changesets
23
24upgrading from 0.15 or 0.16
25---------------------------
26
27there was still some residual badness in the revision graph code in
280.16. we think we've caught it all now (we hope!), and there is now a
29great deal more coordinated effort put into stopping any such thing
30from sneaking in again, but... we have to do something about the
31badness that's already there.
32
33the solution is, another rebuild, like we did for the 0.15 -> 0.16
34transition. this is still obnoxious, still loses a little bit of
35history information (every revision remains exactly reconstructable,
36but rename information and information on who signed which certs are
37both lost), and still requires coordination among your whole team to
38pull of smoothly. we're sorry. we'll try not to do this again.
39
40just in case we _do_ have to do it again, though, and to help make
41this time smoother, we've added support for "epochs". there's a whole
42new section in the manual about all this, but basically, epochs are a
43way to let monotone keep track of who's done a rebuild, so you can't
44accidentally mix together pre-rebuild and post-rebuild databases.
45(epochs will also come in handy when it's time to migrate away from
46SHA1, for instance.) this means you have more of a safety net than
47last time, though you still have to coordinate within your team...
48
49so, the basic procedure is: one designated person gets to perform the
50rebuild, and deal with any missing files (see below). everyone else
51gets to 1) make sure the designated person has sync'ed with everyone,
52because anything that's not in the designated person's database will
53be lost, or at least, hard to deal with, 2) take a break, so the
54designated person can rebuild and test and such without having to deal
55with new commits.
56
57if you're the designated person, then you should:
58 1) make sure you have everyone's changes, and that they know they
59 shouldn't make any more changes until you give the all-clear
60 2) make a backup copy of your database. seriously, do this.
61 $ cp my.db my.db-backup
62 if something goes wrong, and you don't have a backup, there may
63 not be much we can do to help...
64 3) dump your database to SQL text using your old version of
65 monotone, and then reload it using your 0.17 version of
66 monotone. (this will migrate you from SQLite 2 to SQLite 3,
67 which have different on-disk formats.)
68 $ old-monotone --db=my.db db dump > my-db.dumped
69 $ monotone --db=new.db db load < my-db.dumped
70 (if you've been tracking the 0.17 development mainline, you can
71 skip this step. you still need to do all the others.)
72 4) do the usual 'db migrate' command, for migrating a database to a
73 later version:
74 $ monotone --db=new.db db migrate
75 (this will create the new tables needed for epoch support)
76 5) rebuild your ancestry. as mentioned above, this will lose
77 renames and cert signing information (all certs that you trust
78 will be re-issued with your signature; all other certs will be
79 lost), but will also generate new changesets that actually make
80 sense.
81 $ monotone --db=new.db db rebuild
82 6) check your database. this is the rough equivalent of running a
83 'fsck' or a 'scandisk' on your hard drive -- it just goes through
84 and makes sure that everything looks good. it's especially
85 important for detecting missing files; see below.
86 $ monotone --db=new.db db check 2>&1 | tee db-check.log
87 7) look at db-check.log, and if any files were missing, note down
88 their SHA1's, find the files, and load them into the database
89 with "fload".
90 $ monotone --db=new.db fload <missing-file
91 after doing this, run 'db check' again, until you get a clean
92 bill of health. (if you see problems other than missing files
93 and incomplete manifests/incomplete revisions, then there's
94 something more gone wrong, and you might want to ask the list at
95 monotone-devel@nongnu.org.)
96 8) put the new database somewhere where people can netsync to it.
97 (either by putting it there directly, or by creating a new
98 database on your server and pushing to it.)
99 9) tell everyone to create a new, empty database, and pull from your
100 server. (make sure they remember to copy their private keys over
101 from their old database, using 'monotone privkey' and 'monotone
102 read'.)
103
104missing files
105-------------
106
107unfortunately, monotone 0.16 had a bug that may have led to loss of
108data under certain, rare, circumstances. the bug is that, 0.16's
109"rebuild" (and probably "changesetify") commands incorrectly
110constructed root revisions. as a result, if you had any files that
111were in the initial import of your project, and then later deleted,
112without having had any changes made in between, then those files were
113invisible to netsync, and not transferred by "push", "pull", or
114"sync". therefore, if you rebuilt your database at the 0.16 release,
115and then pulled everything into a new database and deleted the
116original database, monotone has lost its record of those files's
117contents; if you attempted to check out a revision containing them you
118would get an assertion error.
119
120hopefully this should be a rare enough problem that most people don't
121run into it. the new 'db check' command detects this problem (indeed,
122it's how it was discovered in the first place), so it should be easy
123to find out whether you have it or not. if you _do_ have it, you need
124to find those missing files, and tell monotone about them. this is
125straightforward, though it may be tricky -- basically, 'db check' will
126tell you the SHA1's of the missing data. you need to find files that
127have those SHA1's, and load them into your master database. (that
128would be the database that you just ran 'db rebuild', as above.)
129
130some places to look:
131 -- old releases of your software
132 -- old copies of your monotone database (e.g., if you still have
133 pre-changesetify backups of it)
134 'cat file <SHA1>' is the useful command here
135 -- the database that you originally ran 'rebuild' or 'changesetify'
136 in, back at the 0.16 release. since the problem only affects
137 netsync, your initial database should be fine
138
139getting the manifest of your initial revision may also be helpful,
140since you can grep it to find the filenames of the missing files. you
141can do this by examining the output of 'cat revision <revision id>',
142and then running 'cat manifest <manifest id>'.
143
144once you've found the files, load them into your database with
145'fload', e.g.:
146 $ monotone --db=new.db fload <a-found-file
147
148if you cannot find the relevant files anywhere, then there's a more
149serious problem; your history is not fully reconstructible, and you
150won't be able to use it with 0.17, because the bug is now fixed. it
151should still be possible to reconstruct all revisions after the
152offending files were deleted, but this requires some code that doesn't
153currently exist; if you actually are in this state, please email
154<monotone-devel@nongnu.org> and we'll work something out.
155
156in the future, the more rigorous checking monotone now does should
157prevent problems like this from arising; in case you're nervous,
158though, you can always run 'db check' to check for problems.

Archive Download this file

Branches

Tags

Quick Links:     www.monotone.ca    -     Downloads    -     Documentation    -     Wiki    -     Code Forge    -     Build Status