← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/upgrade-guide/data_migration.txt

  • Committer: John Arbash Meinel
  • Date: 2008-08-28 20:13:31 UTC
  • mfrom: (3658 +trunk)
  • mto: This revision was merged to the branch mainline in revision 3688.
  • Revision ID: john@arbash-meinel.com-20080828201331-dqffxf54l2heokll
Merge bzr.dev 3658

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/upgrade-guide/data_migration.txt
1
 
Data migration
2
 
##############
3
 
 
4
 
Preparing for data migration
5
 
----------------------------
6
 
 
7
 
Before starting a migration, there are a few important things to do
8
 
first:
9
 
 
10
 
1. Take a complete backup.
11
 
 
12
 
2. Take some time to purge obsolete branches.
13
 
 
14
 
A complete backup gives you a safety net in case anything goes wrong.
15
 
 
16
 
Purging obsolete branches reduces the amount of data that needs to
17
 
be migrated. See `Finding obsolete branches`_ later for some tips
18
 
on doing this.
19
 
 
20
 
 
21
 
Introducing the upgrade-related commands
22
 
----------------------------------------
23
 
 
24
 
There are 3 important commands to be aware of when migrating data.
25
 
 
26
 
* **check** - check a repository, branch or tree for data integrity errors
27
 
 
28
 
* **reconcile** - fix data integrity errors
29
 
 
30
 
* **upgrade** - migrate data to a different format.
31
 
 
32
 
**reconcile** is rarely needed but it's good practice to run **check**
33
 
before and after running **upgrade**.
34
 
 
35
 
For detailed help on these commands, see the `Bazaar User Reference`_.
36
 
 
37
 
.. _Bazaar User Reference: ../user-reference/index.html
38
 
 
39
 
 
40
 
Communicating with your community
41
 
---------------------------------
42
 
 
43
 
To enable a smooth transition to the new format, you should:
44
 
 
45
 
1. Make one person responsible for migrating the trunk.
46
 
 
47
 
2. Test the migration of trunk works successfully.
48
 
 
49
 
3. Schedule a time for the trunk migration and notify your community
50
 
   in advance.
51
 
 
52
 
This advance warning should be long enough for users to have time
53
 
to upgrade Bazaar and any required plugins before the migration date.
54
 
 
55
 
For larger projects, allow some time for the migration itself.
56
 
You should have a good idea of how long the migration will take
57
 
after doing the test migration. It may make sense to do the migration
58
 
on a weekend or a Friday, giving yourself some breathing space if
59
 
things go wrong.
60
 
 
61
 
After the trunk is migrated, you'll need to notify your community
62
 
accordingly, giving them instructions as to how to migrate their
63
 
local branches. Sample instructions are provided later in this
64
 
document.
65
 
 
66
 
 
67
 
Migrating a standalone branch
68
 
-----------------------------
69
 
 
70
 
The steps are:
71
 
 
72
 
1. Run **bzr check**.
73
 
 
74
 
2. If there are errors, try using **bzr reconcile** to fix them.
75
 
   If that fails, file a bug so we can help you resolve the issue
76
 
   and get your trunk clean. If it works, take a backup copy of
77
 
   your now clean trunk.
78
 
 
79
 
2. Run **bzr upgrade --format** where *format* is 2a or later.
80
 
 
81
 
3. Run **bzr check** to confirm the final result is good.
82
 
 
83
 
 
84
 
Migrating branches in a shared repository
85
 
-----------------------------------------
86
 
 
87
 
Upgrade things in the following order:
88
 
 
89
 
1. Upgrade the shared repository.
90
 
2. Upgrade the branches.
91
 
3. Upgrade any lightweight checkouts.
92
 
 
93
 
As in the standalone branch case, be sure to run **check** before
94
 
and after the upgrade to check for any existing or introduced issues.
95
 
 
96
 
 
97
 
Migrating branches on Launchpad
98
 
-------------------------------
99
 
 
100
 
You have two options for upgrading your Launchpad branches.  You can either
101
 
upgrade them remotely or you can upgrade them locally and push the migrated
102
 
branch to Launchpad.  We recommend the latter.  Upgrading remotely currently
103
 
requires a fast, rock solid network connection to the Launchpad servers, and
104
 
any interruption in that connection can leave you with a partially upgraded
105
 
branch.  The instructions below are the safest and often fastest way to
106
 
upgrade your Launchpad branches.
107
 
 
108
 
To allow isolation between public and private branches, Launchpad
109
 
uses stacked branches rather than shared repositories as the core
110
 
technology for efficient branch storage. The process for migrating
111
 
to a new format for projects using Launchpad code hosting is therefore
112
 
different to migrating a personal or in-house project.
113
 
 
114
 
In Launchpad, a project can define a *development series* and associate a
115
 
branch with that series.  The branch then becomes the *focus of development*
116
 
and gets special treatment and a shortcut URL.  By default, if anybody
117
 
branches your project's focus of development and pushes changes back to
118
 
Launchpad, their branch will be stacked on your development focus branch.
119
 
Also, branches can be associated with other Launchpad artifacts such as bugs
120
 
and merge proposals.  All of these things mean that upgrading your focus of
121
 
development branch is trickier.
122
 
 
123
 
Here are the steps to follow:
124
 
 
125
 
1. The nominated person grabs a copy of trunk and does the migration locally.
126
 
 
127
 
2. On Launchpad, unset the current trunk from being the development focus.
128
 
   (This *must* be done or the following step won't work as expected.)
129
 
 
130
 
   1. Go to your project's home page on Launchpad
131
 
 
132
 
   2. Look for "XXX is the current focus of development"
133
 
 
134
 
   3. Click on the edit (pencil) icon
135
 
 
136
 
   4. Click on "Change details" in the portlet on the right
137
 
 
138
 
   5. Scroll down to where it says "Branch: (Optional)"
139
 
 
140
 
   6. Blank out this input field and click "Change"
141
 
 
142
 
3. Push the migrated trunk to Launchpad.  See below if you want your
143
 
   new migrated development focus branch to have the same name as your old
144
 
   pre-migration development focus branch.
145
 
 
146
 
4. Set it as the development focus.  Follow the instructions above but at step
147
 
   5, enter the name of the newly migrated branch you just pushed.
148
 
 
149
 
5. Ask users subscribed to the old trunk to subscribe to the new one.
150
 
 
151
 
In summary, these steps mean that the old trunk is still available and
152
 
existing branches stacked on it will continue to be so. However, the
153
 
development focus has switched to the migrated trunk and any new branches
154
 
pushed to Launchpad for your project will now stack on it.
155
 
 
156
 
You are now ready to tell your community that the new trunk is available
157
 
and to give them instructions on migrating any local branches they have.
158
 
 
159
 
If you want your new migrated development focus branch to have the same name
160
 
as your old pre-migration branch, you need to do a few extra things before you
161
 
establish the new development focus.
162
 
 
163
 
1. Rename your old pre-migration branch; use something like
164
 
   **foo-obsolete-do-not-use**.  You will really not want to delete this
165
 
   because there will be artifacts (bugs, merge proposals, etc.) associated
166
 
   with it.
167
 
 
168
 
2. Rename the new migrated branch to the pre-migration branch's old name.
169
 
 
170
 
3. Re-establish the development focus branch using the new migrated branch's
171
 
   new name (i.e. the old pre-migration branch's original name).
172
 
 
173
 
 
174
 
Migrating local branches after a central trunk has migrated
175
 
-----------------------------------------------------------
176
 
 
177
 
To migrate a standalone branch:
178
 
 
179
 
1. Grab the latest branch from the central location into a
180
 
   new directory.
181
 
 
182
 
2. Pull or merge any changes you've made in your existing branch
183
 
   into the new branch.
184
 
 
185
 
To migrate branches in a shared repository:
186
 
 
187
 
1. Create a fresh shared repository in the new format (2a or later).
188
 
 
189
 
2. Grab the latest branch from the central location into a
190
 
   new directory inside the shared repository.
191
 
 
192
 
3. Decide which of your local branches you want to migrate. (If you
193
 
   haven't already, now's a good time for `Finding obsolete branches`_
194
 
   and purging them, after backing up first of course.)
195
 
 
196
 
4. To migrate each local branch of interest, there are 2 options:
197
 
 
198
 
 * **init** an empty branch in the new repository and **pull** the
199
 
   revisions from the branch in the old repository across.
200
 
 
201
 
 * In the new repository, **branch** from trunk to the new branch
202
 
   name then **merge** your changes from the matching branch in the
203
 
   old repository.
204
 
 
205
 
The first method will give you a branch which is identical (in terms of
206
 
revision history) to the old branch, but it's parent branch will be set to the
207
 
old branch, not your new trunk. If you use this method, you'll probably update
208
 
the ``parent_location`` configuration variable in the ``branch.conf`` file
209
 
with::
210
 
 
211
 
    bzr config parent_location=XXX
212
 
 
213
 
``XXX`` being the URL to your new trunk.
214
 
 
215
 
In contrast, the second approach sets up the parent branch correctly.
216
 
However, it isn't ideal if you're not ready to include all the latest
217
 
revisions from trunk into that branch yet.