Rev 2535: Create a document describing bundles and their motivation. in sftp://rookery/~/public_html/baz2.0/bundle

[Robert Collins]

At sftp://rookery/~/public_html/baz2.0/bundle

------------------------------------------------------------
revno: 2535
revision-id: robertc at robertcollins.net-20070621030632-u20tpto23hcj15td
parent: pqm at pqm.ubuntu.com-20070618210710-6y8wzcqiw2kvxdiy
committer: Robert Collins <robertc at robertcollins.net>
branch nick: bundle
timestamp: Thu 2007-06-21 13:06:32 +1000
message:
  Create a document describing bundles and their motivation.
added:
  doc/developers/bundles.txt     bundles.txt-20070621030528-qkjnugd7iyud6ow3-1
modified:
  doc/developers/index.txt       index.txt-20070508041241-qznziunkg0nffhiw-1
=== added file 'doc/developers/bundles.txt'
--- a/doc/developers/bundles.txt	1970-01-01 00:00:00 +0000
+++ b/doc/developers/bundles.txt	2007-06-21 03:06:32 +0000
@@ -0,0 +1,83 @@
+=======
+Bundles 
+=======
+
+Status
+======
+
+:Date: 2007-06-19
+
+This document describes the current and future design of the bzr bundle facility.
+
+.. contents::
+
+Motivation
+==========
+
+Bundles are intended to be a compact binary representation of the changes done within
+a branch for transmission between users. Bundles should be able to be used
+easily and seamlessly - we want to avoid having a parallel set of commands to
+get data from within a bundle.
+
+A related concept is **merge directives** which are used to transmit bzr merge
+and merge-like operations from one user to another in such a way that the
+recipient can be sure they get the correct data the initiator desired.
+
+Desired features
+================
+
+* A bundle should be able to substitute for the entire branch in any bzr
+  command that operates on branches in a read only fashion.
+* Bundles should be as small as possible without losing data to keep them
+  feasible for including in emails.
+
+Historical Design
+=================
+
+Not formally documented, the current released implementation can be found
+in bzrlib.bundle.serializer. One key element is that this design included
+parts of the branch data as human readable diffs; which were then subject
+to corruption by transports such as email.
+
+June 2007 Design
+================
+
+To be documented.
+
+Future Plans
+============
+
+Bundles will be implemented as a 'Shallow Branch' with the branch and
+repository data combined into a single file. This removes the need to
+special case bundle handling for all command which read from branches.
+
+Physical encoding
+-----------------
+
+Bundles will be encoded using the bzr pack format. Within the pack the
+branch metadata will be serialised as a BzrMetaDir1 branch entry. The
+Repository data added by the revisions contained in the bundle will be
+encoded using multi parent diffs as they are the most pithy diffs we are
+able to create today in the presence of merges. XXX More details needed?
+
+Code reuse
+----------
+
+Ideally we can reuse our BzrMetaDir based branch formats directly within a
+Bundle by layering a Transport interface on top of the pack - or just
+copying the data out into a readonly memory transport when we read the
+pack. This suggests we will have a pack specific Control instance,
+replacing the usual 'BzrDir' instance, but use the Branch class as-is.
+
+For the Repository access, we will create a composite Repository using the
+planned Repository Stacking API, and a minimal Repository implementation
+that can work with the multi parent diffs within the bundle.
+
+We will need access to a branch that has the basis revision of the bundle
+to be able to construct revisions from within it - this is a requirement
+for Shallow Branches too, so hopefully we can define a single mechanism at
+the Branch level to gain access to that.
+
+
+   vim: ft=rst tw=74 ai
+

=== modified file 'doc/developers/index.txt'
--- a/doc/developers/index.txt	2007-06-12 14:57:07 +0000
+++ b/doc/developers/index.txt	2007-06-21 03:06:32 +0000
@@ -2,22 +2,36 @@
 Bazaar Developers Guide
 =======================
 
--------------------
+###################
 Documentation index
--------------------
+###################
+
+Process
+=======
 
 * `General HACKING HOWTO <HACKING.htm>`_
 
   Guide to policies and tools for working on Bazaar itself.
 
+* `Profiling notes <profiling.htm>`_
+
+  Instructions on how to profile bzr code and visualize the results.
+
+Plans
+=====
+
 * `Performance roadmap <performance-roadmap.htm>`_
 
   The roadmap for fixing performance in bzr over the next few releases.
 
+Specifications
+==============
+
+* `Bundles <bundles.htm>`_
+
+  All about bzr bundles.
+
 * `Container format <container-format.htm>`_
 
   Notes on a container format for streaming and storing Bazaar data.
 
-* `Profiling notes <profiling.htm>`_
-
-  Instructions on how to profile bzr code and visualize the results.