Rev 2543: (robertc) Create a document describing bundles and their motivation. in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 2543
revision-id: pqm at pqm.ubuntu.com-20070621055651-p2zqigyl0rju375h
parent: pqm at pqm.ubuntu.com-20070621052237-2phm1z5dg4arrwnk
parent: robertc at robertcollins.net-20070621030632-u20tpto23hcj15td
committer: Canonical.com Patch Queue Manager<pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2007-06-21 06:56:51 +0100
message:
  (robertc) 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
    ------------------------------------------------------------
    revno: 2534.1.1
    merged: 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 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.