← 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

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 runing **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 transistion 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
To allow isolation between public and private branches, Launchpad
 
101
uses stacked branches rather than shared repositories as the core
 
102
technology for efficient branch storage. The process for migrating
 
103
to a new format for projects using Launchpad code hosting is therefore
 
104
different to migrating a personal or in-house project.
 
105
 
 
106
Here are the steps to follow:
 
107
 
 
108
1. The nominated person grabs a copy of trunk and does the migration.
 
109
 
 
110
2. On Launchpad, unset the current trunk from being the development focus.
 
111
   (This *must* be done or the following step won't work as expected.)
 
112
 
 
113
3. Push the migrated trunk to Launchpad.
 
114
 
 
115
4. Set it as the development focus.
 
116
 
 
117
5. Ask users subscribed to the old trunk to subscribe to the new one.
 
118
 
 
119
In summary, these steps mean that the old trunk is still available and
 
120
existing branches stacked on it will continue to be so. However, the
 
121
development focus has switched to the migrated trunk and any new branches
 
122
pushed to Launchpad for your project will now stack on it.
 
123
 
 
124
You are now ready to tell your community that the new trunk is available
 
125
and to give them instructions on migrating any local branches they have.
 
126
 
 
127
 
 
128
Migrating local branches after a central trunk has migrated
 
129
-----------------------------------------------------------
 
130
 
 
131
To migrate a standalone branch:
 
132
 
 
133
1. Grab the latest branch from the central location into a
 
134
   new directory.
 
135
 
 
136
2. Pull or merge any changes you've made in your existing branch
 
137
   into the new branch.
 
138
 
 
139
To migrate branches in a shared repository:
 
140
 
 
141
1. Create a fresh shared repository in the new format (2a or later).
 
142
 
 
143
2. Grab the latest branch from the central location into a
 
144
   new directory inside the shared repository.
 
145
 
 
146
3. Decide which of your local branches you want to migrate. (If you
 
147
   haven't already, now's a good time for `Finding obsolete branches`_
 
148
   and purging them, after backing up first of course.)
 
149
 
 
150
4. To migrate each local branch of interest, there are 2 options:
 
151
 
 
152
 * **init** an empty branch in the new repository and **pull** the
 
153
   revisions from the branch in the old repository across.
 
154
 
 
155
 * In the new repository, **branch** from trunk to the new branch
 
156
   name then **merge** your changes from the matching branch in the
 
157
   old repository.
 
158
 
 
159
The first method will give you a branch which is identical (in terms
 
160
of revision history) to the old branch, but it's parent branch will
 
161
be set to the old branch, not your new trunk. If you use this method,
 
162
you'll probably want to edit your branch.conf file to update the
 
163
parent branch setting.
 
164
 
 
165
In contrast, the second approach sets up the parent branch correctly.
 
166
However, it isn't ideal if you're not ready to include all the latest
 
167
revisions from trunk into that branch yet.