[MERGE] improved help on storage formats

[Martin Pool]

On 12 Dec 2008, Ian Clatworthy <ian.clatworthy at internode.on.net> wrote:
> Matthew D. Fuller wrote:
> > On Thu, Dec 11, 2008 at 06:10:18PM +1000 I heard the voice of
> > Ian Clatworthy, and lo! it spake thus:
> >> This patch improves the help by:
> > 
> > This is a very good and necessary thing to do.  However...
> 
> Matthew/Stephen,
> 
> [snip]
> 
> Thanks for a heap of suggestions for improvements. I like many
> of them but I'm against a separate topic for experimental formats
> - it ought to be just one most of the time after the rich-root
> duality goes.
> 
> So I propose the following topics:
> 
> * formats - high level explanation, decision tree, rich root
>   explanation
> * current-formats - Matthew's list
> * other-formats - experimental & deprecated stuff

I was concerned at first that not actually listing the formats in 'help
formats' would still make it look like it's too complex.  But in fact,
the ones you do need to know about are mentioned there, during the
checklist.

The following needn't block merges:

Incidentally for reviews like this it may help to include the output in
your mail.

+If some of your developers are unable to use the most recent
+version of Bazaar (due to corporate policy say), be sure to
+adjust the guidelines above accordingly. For example, you may
+need to select 1.6 instead of 1.9 if your company has standardized
+on Bazaar 1.7.

This sounds a bit corporate, and it doesn't need to be: people might be
waiting for e.g. a distro package update, and I'd change
/company/project/ in the latter to be more precise.

The updates to format descriptions are good, but many are now described
by backward references, e.g. from 1.9 to 1.6.  I don't know if this
means much to readers: it's true they may have code or subcomponents in
common but at the user level they're opaque.  Readers want to
know what interoperability, feature or performance implications there
would be in upgrading.  So:

 format_registry.register_metadir('1.9',
     'bzrlib.repofmt.pack_repo.RepositoryFormatKnitPack6',
-    help='A branch and pack based repository that uses btree indexes.
     ',
+    help='An enhancement to 1.6 that introduces btree indexes. These indexes '
+         'are smaller in size, have smarter caching and provide faster '
+         'performance for most operations.',

Maybe just "A repository format with B+tree indexes..."

+    deprecated=True)

Will this cause these formats to generate warnings to make an upgrade?

-- 
Martin      <http://launchpad.net/~mbp>