1
==============================
2
Development repository formats
3
==============================
7
Using development repository formats
8
====================================
13
We believe that we can continue to gain substantial performance benefits
14
by altering the repository storage in bzr. The more feedback we can get
15
on the changes during the development process the better.
17
To make it possible to get more feedback we are going to expose the
18
current development formats to the users of our development trunk
19
'bzr.dev'. The technical details of the individual formats are at the
25
The current development format will be called 'development'. Each time
26
the development format changes, the prior development format will be
27
renamed to e.g. 'development0', 'development1' etc.
29
When a release of bzr is done, all the older numbered development
30
formats will be removed from 'bzr.dev', so we will not be carrying the
31
code for them around indefinately.
33
Support for upgrade and migration
34
---------------------------------
36
The preservation and renaming policy makes it quite safe for users to
37
test out development formats (though we cannot guarantee bugs of course
38
- it is development code):
40
- users of a given development format can always get back onto regular
41
formats by switching to the next bzr released version which is
42
guaranteed to be able to upgrade from that development format.
43
- users that routinely use bzr.dev should upgrade to the most recent
44
development version available before pulling in bzr.dev changes
45
around release time, as that is when old format cleanups will occur.
47
We cannot guarantee backwards compatability though, because some of the
48
planned work may be 'upgrade only'. Please see ``bzr help formats`` for
49
the text of the 'development' format which will indicate its
50
compatability with other formats if you need to interoperate with
51
users or services that do not have bzr.dev.
53
Before converting to a development format
54
-----------------------------------------
56
Run a ``bzr check`` with the version of bzr that you will be using.
57
``bzr check`` gets updated as we find new things that are inconsistent
58
with existing repositories. While only a small number of repositories
59
are likely to have any given error, it is best to check just in case.
61
If ``bzr check`` reports a problem, run this command::
65
Note that reconcile can take many hours, particularly if you are
66
reconciling one of the 'knit' or 'dirstate' format repositories. If you
67
have such a repository, consider upgrading it to 'pack-0.92' first,
68
which will perform reconcile significantly faster.
70
Creating a new development format branch
71
----------------------------------------
73
If you're starting a project from scratch, it's easy to make it a
74
``development`` one. Here's how::
77
bzr init --development
79
bzr commit -m "initial import"
81
In other words, use the normal sequence of commands but add the
82
``--development`` option to the ``init`` command.
85
Creating a new development format repository
86
--------------------------------------------
88
If you're starting a project from scratch and wish to use a shared repository
89
for branches, you can make it a ``development`` repository like this::
92
bzr init-repo --development .
96
bzr commit -m "initial import"
98
In other words, use the normal sequence of commands but add the
99
``--development`` option to the ``init-repo`` command.
101
Upgrading an existing branch or repository to development
102
---------------------------------------------------------
104
If you have an existing branch and wish to migrate it to
105
a ``development`` format, use the ``upgrade`` command like this::
107
bzr upgrade --development path-to-my-branch
109
If you are using a shared repository, run::
111
bzr upgrade --development ROOT_OF_REPOSITORY
113
to upgrade the history database. Note that this will not
114
alter the branch format of each branch, so
115
you will need to also upgrade each branch individually
116
if you are upgrading from an old (e.g. < 0.17) bzr.
117
More modern bzr's will already have the branch format at
118
our latest branch format which adds support for tags.
120
Starting a new development format branch from one in an older format
121
--------------------------------------------------------------------
123
This can be done in one of several ways:
125
1. Create a new branch and pull into it
126
2. Create a standalone branch and upgrade its format
127
3. Create a knitpack shared repository and branch into it
129
Here are the commands for using the ``pull`` approach::
131
bzr init --development my-new-branch
133
bzr pull my-source-branch
135
Here are the commands for using the ``upgrade`` approach::
137
bzr branch my-source-branch my-new-branch
139
bzr upgrade --development .
141
Here are the commands for the shared repository approach::
144
bzr init-repo --development .
145
bzr branch my-source-branch my-new-branch
148
As a reminder, any of the above approaches can fail if the source branch
149
has inconsistent data within it and hasn't been reconciled yet. Please
150
be sure to check that before reporting problems.
152
Develoment formats for bzr-svn users
153
------------------------------------
155
If you are using ``bzr-svn`` or are testing the prototype subtree support,
156
you can still use and assist in testing the development formats. The
157
commands to use are identical to the ones given above except that the
158
name of the format to use is ``development-subtree``.
160
**WARNING**: Note that bzr only supports one-way conversion **to** the
161
subtree format ``development-subtree``. Once you are using
162
``development-subtree`` you cannot pull or merge back into a regular
163
format such as ``pack-0.92``, ``development`` etc.
165
The ``development-subtree`` format is required for the bzr-svn
166
plug-in but should otherwise not be used until the subtree feature is
172
If you need any help or encounter any problems, please contact the developers
173
via the usual ways, i.e. chat to us on IRC or send a message to our mailing
174
list. See http://wiki.bazaar.canonical.com/BzrSupport for contact details.
180
When to create a new development format
181
---------------------------------------
183
Whenever a code change will result in incorrect behaviour with existing
184
``development`` repositories. Changes in push/pull/init/commit/merge
185
have all been known to do this in the past.
187
How to create a new development format
188
--------------------------------------
190
1. Register two new formats with the next available sequence number.
191
e.g. ``development1`` and ``development1-subtree``. (You can see the
192
current development format for an example.
195
* Use your new development repository/branch/tree classes
196
* Have really bare bones help - something like 'changes X to be Y
197
see ...developers/development-repo.html'
198
* Be hidden and experimental.
199
2. Change the repository class (or branch or tree) in the
200
``development`` and ``development-subtree`` formats to point to the
201
new class you are creating.
202
3. Add a new development format (and tests!). Repository formats are in
203
``bzrlib.repofmt``. You probably want to reproduce the current
204
development format from ``bzrlib.repofmt.pack_repo`` with just new
205
disk format strings, ``_get_matching_bzrdir`` and help.
206
4. Register your development format with the various registries. At the
207
moment you need to update:
209
1. ``bzrlib/bzrdir.py`` to register the WT/Branch/Repository
212
2. ``bzrlib/workingtree.py``, ``bzrlib/branch.py``,
213
``bzrlib/repository.py``, each one maintains a direct list of
214
their respective formats.
216
3. For repositories, you also need to update the InterKnit1and2
217
class. This is responsible for converting between rich-root and
218
non-rich-root repositories.
220
4. For repositories based on KnitPackRepository, you need to update
221
``bzrlib/tests/test_pack_repository.py`` to add the class to the
224
5. Alter any other things that do class based tests. The easiest way
225
to find these is a grep for Development in bzrlib - and please
226
refactor as you find these to reduce the relevance this step has,
227
as it should not need to exist.
228
6. Now subclass/create from scratch/whatever the live object code you
229
need to change to introduce your new format. Keep in mind that
230
eventually it will become the default format, so please don't keep
231
subclassing the last releases code, rather consider making the last
232
releases code a subclass of your new code (if there is a lot in
233
common) so that we can eventually remove that format once it becomes
234
ancient (or relegate it to a plugin).
235
7. Once you have made the changes that required a new disk format, you
236
should submit the resulting branch to be merged. Other changes - to
237
take advantage of whatever new feature you have added - should be
238
sent in separately, because the disk level changes are a contention
239
point between multiple developers.
247
Not currently available, as our development formats are all rich root or
250
development-rich-root
251
---------------------
253
Currently an alias for Development6Subtree
258
Currently an alias for Development6Subtree
260
Development6RichRoot[Subtree]
261
-----------------------------
263
These formats use the new groupcompress delta compress and a CHK(Content
264
Hash Key) based inventory store which is much faster at incremental
265
operations than the prior XML based store.
266
*Note* Converting from a non-rich-root to a rich-root format is a
267
one-way upgrade, and you cannot merge back afterwards: using this format
268
for everyday use is likely to cause all developers of a project to
269
upgrade to a rich-root format themselves. This is fine, as bzr is moving
270
to make rich-root formats the default and to get all users to upgrade,
271
but we have not finalised the migration process, and until we do do not
272
recomment that casual users upgrade. Users of bzr-svn are already using
273
rich-root formats and can test with this with impunity.
277
vim: tw=72 ft=rst expandtab
added
removed
doc/developers/development-repo.txt
