Repository and branch format descriptions - bug 264730

[John Arbash Meinel]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


...

> So, would it be appropriate, from Bazaar's POV, to rewrite the
> pack_repo.py strings? Or should I write my own versions of them for
> the Launchpad web UI? I'd rather do the former because I have a
> suspicion that it'd be useful to Bazaar users as well as people using
> Launchpad.

The strings are not just in pack_repo.py, they are also in knit_repo.py
and a few other places. Certainly pack_repo.py has the more common ones,
though.

There are 2 strings to be aware of.

1) 'get_format_string()' do *NOT* touch these. This is what we write
(and read) from disk to indicate the format.

2) 'get_format_description()' this can be modified as we see fit, as
they are meant for display to the user.

At the moment, they are only displayed to the user when they run "bzr
info -v". And that code expects them to be single-line strings.

I think it would be fine for them to be a little bit more verbose, but
if you find you need more than one line, we need to update the "info"
code to support that.


> 
> Either way, I'd be grateful for any help in making sense of the
> existing strings and looking at how we can make them more useful.

The basic flow of repository formats is:

Flat	really-really-really old (0.0.7, IIRC)
Weave	pre 0.8.2
Knit	From 0.8.2 -> 0.92, stores the history of each file in a
        separate "knit"
Pack	0.92 => present, clusters the histories of all files together in
	a 'pack'. Allows us to request the texts for multiple files at
        the same time, etc.

There are some optional features on the repositories. Mostly this is
just a flag to indicate compatibility.

(none)		The default
rich-root	Support versioning the root directory as an real entity.
subtree		(beta) Includes rich-root, and the ability to version a
		reference to an external tree. (nested trees, similar to
		svn:externals)

There are also other features which are incompatible with older clients,
so we have to introduce a new format, just to make sure older clients
don't try to access the data incorrectly.

stacking	Added in 1.6, allows a Branch to indicate that there is
		another repository that can be used to access more data
		that is not present locally.

btree		Added in 1.9. an one improvement to our pack index
		layer. Changing from a plain "sorted list" file that we
		bisect into, into a "btree" index. Uses compressed
		fixed-length pages, and a btree, which allows for
		smaller indexes, and much better specificity when
		searching for a small number of records. (log2(N) versus
		log100(N)) Also has better work on when to cache, what
		requests to expand, etc.


Things get a little cluttered, because Branches also have a few formats,
and WorkingTrees do as well. And at the moment, our UI tries to present
a single name for various composites of these.

Branch5		Has a revision-history file, which holds all mainline
		revisions. (does not scale well with long-lived
		projects)
Branch6		Changes to use a branch.conf file to collect
		meta-information together in one file, rather than
		one-file-per-info.
		Also only contains a "last-revision" file, which points
		at the revno & revision_id of the tip of the branch.
Branch7		Used to enable stacking. Exists so that older clients
		that cannot handle stacking, don't try to access the
		branch incorrectly.


WorkingTree2	Pre 0.8.2, stores the working-tree state as an XML file
WorkingTree3	0.8.2 => 0.15, pre 'dirstate', stores the state in the
		same way, just in a slightly different location.
WorkingTree4	'dirstate'. Stores the state as a custom-serialized
		file. Which also combines the previous state "inline".
		Makes accessing current + base information for a single
		record easier (locality of reference).

> 
> I've been reading through http://bazaar-vcs.org/BazaarFormats and that
> helps to some extent - in particular the Weave and Knit pages - but it
> appears the page is not comprehensive.
> 
> Thanks :)
> 

So getting back to the Repository formats, we should have:

Knit1		Plain knit format repository
		(--knit, --dirstate)
Knit2		Doesn't seem to exist... ??
Knit3		Knit format + subtree support (developmental)
		(--dirstate-subtree)
Knit4		Knit format + 'rich-root' (--rich-root)

KnitPack1	Plain pack format repository (--pack-0.92)
KnitPack3	Pack + subtree (--pack-0.92-subtree)
KnitPack4	Pack + rich-root (--rich-root-pack)
KnitPack5	Pack + stacking (--1.6)
KnitPack5RRoot	Pack + rich-root (--1.6.1-rich-root)
KnitPack5RRootBroken	was the rich root format released in 1.6, but
			did not use the right serializers, etc. Unlikely
			that anyone is actually using it anymore
KnitPack6	Pack + stacking + btree (--1.9)
KnitPack6RRoot	Pack + stacking + btree + rich-root (--1.9-rich-root)

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkk/6sIACgkQJdeBCYSNAANTOwCfZ4HueBIbFbiuRQNL+fmQg9U6
Is0An3H2km20n6c2wmk8VY1xNbmepntc
=Y05c
-----END PGP SIGNATURE-----