monotone

monotone Mtn Source Tree

Root/UPGRADE

1upgrading monotone to 0.28
2==========================
3
4How to read this file:
5 - Figure out what version of monotone you are upgrading from, let's
6 say 0.22, for example.
7 - Read down the list, and at each "version X or earlier" line, those
8 instructions apply if X is larger than 0.22. So, for instance,
9 the "0.25 or earlier" instructions _and_ the "0.23 or earlier"
10 instructions both apply.
11 - If there are no entries that apply, then there is nothing to do.
12 For instance, when upgrading from 0.23 to 0.24, no action was
13 necessary.
14 - No matter what, reading the release notes in NEWS is a good idea.
15 Changes to things like command line switches, new commands, etc.,
16 will be described there, not here.
17
18If you are upgrading from:
19 - 0.25 or earlier: Please read this section carefully. We have
20 modified the textual format used by revisions and manifests; old
21 monotones cannot parse the new format, and new monotones cannot
22 parse the old format, except to convert it to the new format. See
23 NEWS before upgrading. Your project must rebuild its history;
24 this is irreversible and creates a flag day -- everyone in your
25 project must switch over at the same time.
26
27 You will not be able to sync revisions between pre- and post-
28 migration databases, and each project should only run the
29 migration ONCE, on ONE database. Pick a person to do the
30 migration, they do it, once they're done, everyone else does a
31 fresh pull from them.
32
33 You should probably do some test migrations locally first to make
34 sure everything seems to be working, before running your real
35 migration. To run the real migration:
36 1) get everyone to commit and push their changes to the database
37 chosen for migration (such as a central server if you use
38 one); local dbs and working copies will be broken by this
39 migration.
40 2) shut down the server
41 3) run 'cp server.db server.db.backup'
42 4) run 'mtn db migrate --db server.db'
43 5) run 'mtn db rosterify --db server.db'
44 6) do whatever tests you like to make sure things look reasonable
45 7) make sure that your server's firewall is set up to allow
46 connections on the new netsync port: 4691
47 8) start up the server
48 9) tell everyone to do a new pull into a fresh database, using
49 the new version of monotone.
50 This migration is "best effort"; bugs in rename handling in the
51 old code mean that some histories contain bogosities that cannot
52 be migrated. However, it makes an effort to preserve everything
53 it can (including renames), and does guarantee that at each
54 entry in the history graph, the tree layout and file contents are
55 preserved exactly.
56
57 The largest changes are that after upgrading, all revision ids
58 will change, and, as a consequence, all certs must be reissued.
59 This means that after upgrading, all certs will be signed by the
60 person who performed the upgrade, rather than their original
61 issuer. This is a basic property of how signatures work, so
62 there's little we can do about it.
63
64 If you have any private branches, and are not your project's
65 "designated migrator", then it is still possible to preserve your
66 branches. However, this requires some more understanding of what
67 exactly is going on, and is outside the scope of this document.
68 See http://venge.net/monotone/wiki/RosterifyingPrivateBranches
69 for one approach, and if you don't understand the logic behind
70 those commands, then we're happy to explain things in more detail
71 on the mailing list (monotone-devel@nongnu.org) or IRC (#monotone
72 on irc.OFTC.net).
73
74 We tentatively hope that this is the last time we will have to
75 change the revision/manifest formats and have a flag day of this
76 magnitude; but only experience will let us know for certain.
77
78 If you have any questions or concerns about this process, please
79 let us know via email (monotone-devel@nongnu.org) or discuss it on
80 IRC (#monotone on irc.OFTC.net).
81
82 - 0.23 or earlier: keys are now stored in ~/.monotone/keys (Unix,
83 OS X), or %APPDATA%\Monotone\keys (Windows). You must run 'db
84 migrate' against each of your databases; this will automatically
85 migrate the keys. See NEWS for details.
86 Command line syntax for 'serve' has changed; please adjust startup
87 scripts accordingly.
88 On Windows only, monotone now looks in a different place for the
89 monotonerc file; see NEWS for 0.24 for details.
90
91 - 0.21 or earlier: hooks governing netsync read permission have
92 changed again; see NEWS for 0.22.
93
94 - 0.19 or earlier: there are incompatible command line and server
95 configuration changes; see NEWS for 0.20.
96
97 - 0.18 or earlier: if you have created a ~/.monotonerc, rename it to
98 ~/.monotone/monotonerc, so monotone will still find it.
99
100 - 0.17: simply make a backup of your databases, just in case, and
101 run "db migrate" on each.
102
103 - 0.15 or 0.16: see below
104 - 0.14 or earlier: see file README.changesets
105
106upgrading from 0.15 or 0.16
107---------------------------
108
109there was still some residual badness in the revision graph code in
1100.16. we think we've caught it all now (we hope!), and there is now a
111great deal more coordinated effort put into stopping any such thing
112from sneaking in again, but... we have to do something about the
113badness that's already there.
114
115the solution is, another rebuild, like we did for the 0.15 -> 0.16
116transition. this is still obnoxious, still loses a little bit of
117history information (every revision remains exactly reconstructable,
118but rename information and information on who signed which certs are
119both lost), and still requires coordination among your whole team to
120pull of smoothly. we're sorry. we'll try not to do this again.
121
122just in case we _do_ have to do it again, though, and to help make
123this time smoother, we've added support for "epochs". there's a whole
124new section in the manual about all this, but basically, epochs are a
125way to let monotone keep track of who's done a rebuild, so you can't
126accidentally mix together pre-rebuild and post-rebuild databases.
127(epochs will also come in handy when it's time to migrate away from
128SHA1, for instance.) this means you have more of a safety net than
129last time, though you still have to coordinate within your team...
130
131so, the basic procedure is: one designated person gets to perform the
132rebuild, and deal with any missing files (see below). everyone else
133gets to 1) make sure the designated person has sync'ed with everyone,
134because anything that's not in the designated person's database will
135be lost, or at least, hard to deal with, 2) take a break, so the
136designated person can rebuild and test and such without having to deal
137with new commits.
138
139if you're the designated person, then you should:
140 1) make sure you have everyone's changes, and that they know they
141 shouldn't make any more changes until you give the all-clear
142 2) make a backup copy of your database. seriously, do this.
143 $ cp my.db my.db-backup
144 if something goes wrong, and you don't have a backup, there may
145 not be much we can do to help...
146 3) dump your database to SQL text using your old version of
147 monotone, and then reload it using your 0.17 version of
148 monotone. (this will migrate you from SQLite 2 to SQLite 3,
149 which have different on-disk formats.)
150 $ old-monotone --db=my.db db dump > my-db.dumped
151 $ monotone --db=new.db db load < my-db.dumped
152 (if you've been tracking the 0.17 development mainline, you can
153 skip this step. you still need to do all the others.)
154 4) do the usual 'db migrate' command, for migrating a database to a
155 later version:
156 $ monotone --db=new.db db migrate
157 (this will create the new tables needed for epoch support)
158 5) rebuild your ancestry. as mentioned above, this will lose
159 renames and cert signing information (all certs that you trust
160 will be re-issued with your signature; all other certs will be
161 lost), but will also generate new changesets that actually make
162 sense.
163 $ monotone --db=new.db db rebuild
164 6) check your database. this is the rough equivalent of running a
165 'fsck' or a 'scandisk' on your hard drive -- it just goes through
166 and makes sure that everything looks good. it's especially
167 important for detecting missing files; see below.
168 $ monotone --db=new.db db check 2>&1 | tee db-check.log
169 7) look at db-check.log, and if any files were missing, note down
170 their SHA1's, find the files, and load them into the database
171 with "fload".
172 $ monotone --db=new.db fload <missing-file
173 after doing this, run 'db check' again, until you get a clean
174 bill of health. (if you see problems other than missing files
175 and incomplete manifests/incomplete revisions, then there's
176 something more gone wrong, and you might want to ask the list at
177 monotone-devel@nongnu.org.)
178 8) put the new database somewhere where people can netsync to it.
179 (either by putting it there directly, or by creating a new
180 database on your server and pushing to it.)
181 9) tell everyone to create a new, empty database, and pull from your
182 server. (make sure they remember to copy their private keys over
183 from their old database, using 'monotone privkey' and 'monotone
184 read'.)
185
186missing files
187-------------
188
189unfortunately, monotone 0.16 had a bug that may have led to loss of
190data under certain, rare, circumstances. the bug is that, 0.16's
191"rebuild" (and probably "changesetify") commands incorrectly
192constructed root revisions. as a result, if you had any files that
193were in the initial import of your project, and then later deleted,
194without having had any changes made in between, then those files were
195invisible to netsync, and not transferred by "push", "pull", or
196"sync". therefore, if you rebuilt your database at the 0.16 release,
197and then pulled everything into a new database and deleted the
198original database, monotone has lost its record of those files's
199contents; if you attempted to check out a revision containing them you
200would get an assertion error.
201
202hopefully this should be a rare enough problem that most people don't
203run into it. the new 'db check' command detects this problem (indeed,
204it's how it was discovered in the first place), so it should be easy
205to find out whether you have it or not. if you _do_ have it, you need
206to find those missing files, and tell monotone about them. this is
207straightforward, though it may be tricky -- basically, 'db check' will
208tell you the SHA1's of the missing data. you need to find files that
209have those SHA1's, and load them into your master database. (that
210would be the database that you just ran 'db rebuild', as above.)
211
212some places to look:
213 -- old releases of your software
214 -- old copies of your monotone database (e.g., if you still have
215 pre-changesetify backups of it)
216 'cat file <SHA1>' is the useful command here
217 -- the database that you originally ran 'rebuild' or 'changesetify'
218 in, back at the 0.16 release. since the problem only affects
219 netsync, your initial database should be fine
220
221getting the manifest of your initial revision may also be helpful,
222since you can grep it to find the filenames of the missing files. you
223can do this by examining the output of 'cat revision <revision id>',
224and then running 'cat manifest <manifest id>'.
225
226once you've found the files, load them into your database with
227'fload', e.g.:
228 $ monotone --db=new.db fload <a-found-file
229
230if you cannot find the relevant files anywhere, then there's a more
231serious problem; your history is not fully reconstructible, and you
232won't be able to use it with 0.17, because the bug is now fixed. it
233should still be possible to reconstruct all revisions after the
234offending files were deleted, but this requires some code that doesn't
235currently exist; if you actually are in this state, please email
236<monotone-devel@nongnu.org> and we'll work something out.
237
238in the future, the more rigorous checking monotone now does should
239prevent problems like this from arising; in case you're nervous,
240though, 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