← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/bundles.txt

Turn completion assertions into separate methods.

Many common assertions used to be expressed as arguments to the complete
method.  This makes the checks more explicit, and the code easier to read.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/bundles.txt
1
 
=======
2
 
Bundles
3
 
=======
4
 
 
5
 
Status
6
 
======
7
 
 
8
 
:Date: 2007-06-19
9
 
 
10
 
This document describes the current and future design of the bzr bundle facility.
11
 
 
12
 
.. contents::
13
 
 
14
 
Motivation
15
 
==========
16
 
 
17
 
Bundles are intended to be a compact binary representation of the changes done within
18
 
a branch for transmission between users. Bundles should be able to be used
19
 
easily and seamlessly - we want to avoid having a parallel set of commands to
20
 
get data from within a bundle.
21
 
 
22
 
A related concept is **merge directives** which are used to transmit bzr merge
23
 
and merge-like operations from one user to another in such a way that the
24
 
recipient can be sure they get the correct data the initiator desired.
25
 
 
26
 
Desired features
27
 
================
28
 
 
29
 
* A bundle should be able to substitute for the entire branch in any bzr
30
 
  command that operates on branches in a read only fashion.
31
 
* Bundles should be as small as possible without losing data to keep them
32
 
  feasible for including in emails.
33
 
 
34
 
Historical Design
35
 
=================
36
 
 
37
 
Not formally documented, the current released implementation can be found
38
 
in bzrlib.bundle.serializer. One key element is that this design included
39
 
parts of the branch data as human readable diffs; which were then subject
40
 
to corruption by transports such as email.
41
 
 
42
 
June 2007 Design
43
 
================
44
 
`Bundle Format 4 spec`_
45
 
 
46
 
.. _Bundle Format 4 spec: bundle-format4.html
47
 
 
48
 
 
49
 
Future Plans
50
 
============
51
 
 
52
 
Bundles will be implemented as a 'Shallow Branch' with the branch and
53
 
repository data combined into a single file. This removes the need to
54
 
special case bundle handling for all command which read from branches.
55
 
 
56
 
Physical encoding
57
 
-----------------
58
 
 
59
 
Bundles will be encoded using the bzr pack format. Within the pack the
60
 
branch metadata will be serialised as a BzrMetaDir1 branch entry. The
61
 
Repository data added by the revisions contained in the bundle will be
62
 
encoded using multi parent diffs as they are the most pithy diffs we are
63
 
able to create today in the presence of merges. XXX More details needed?
64
 
 
65
 
Code reuse
66
 
----------
67
 
 
68
 
Ideally we can reuse our BzrMetaDir based branch formats directly within a
69
 
Bundle by layering a Transport interface on top of the pack - or just
70
 
copying the data out into a readonly memory transport when we read the
71
 
pack. This suggests we will have a pack specific Control instance,
72
 
replacing the usual 'BzrDir' instance, but use the Branch class as-is.
73
 
 
74
 
For the Repository access, we will create a composite Repository using the
75
 
planned Repository Stacking API, and a minimal Repository implementation
76
 
that can work with the multi parent diffs within the bundle.
77
 
 
78
 
We will need access to a branch that has the basis revision of the bundle
79
 
to be able to construct revisions from within it - this is a requirement
80
 
for Shallow Branches too, so hopefully we can define a single mechanism at
81
 
the Branch level to gain access to that.
82
 
 
83
 
 
84
 
..
85
 
   vim: ft=rst tw=74 ai