[RFC] proposed user doc for nested trees

[Stephen J. Turnbull]

Aaron Bentley writes:

 > > But we *could* guarantee that when we fetch the historical revision of
 > > the containing tree, will will also fetch the referenced revision of all
 > > subbranches regardless of whether they are in the ancestry of any given
 > > branch.
 > 
 > I've already described a very similar guarantee in
 > http://bazaar-vcs.org/NestedTreesDesign#pull-and-non-initial-push

That section uses the term "upper branch".  I think that means
"containing branch".  If so you should stick to that, I think.

 > It doesn't address garbage-collection, though.

By default the local branch's repository should contain *all* data
needed to reconstruct any revision that is reachable from *any* head
in the local branch.  If you GC a head (because there's no known
external reference) then, and only then, do any of its prerequisite
data become GC candidates.  That's just the definition, of course, but
if it implies that you need to fetch all revisions into a particular
repository, then do that.

 > Both guarantees would fetch the revisions into the repository of the
 > subbranch, it's just that yours would require the repository of the
 > subbranch to be the same as the repository of the containing branch.

Yes, please.  Anything else is "premature optimization."  If users
decide that they want to set their own GC policies, and optimize
storage by using branches that cross repositories (via nested
branches), then you should allow it, I suppose.

 > > I also prefer an 'everything is in this repository over here' approach.
 > > Whether that is just requiring you to be using a shared repository when
 > > using subtrees... I'm okay with that.
 > 
 > What would you think if our subtree repository format was always a
 > shared repository?  Upgrading to support nested trees would then
 > automatically make the repo shared.

I think that is the best way to go.  It seems to me that it should
make things much simpler than trying to construct cross-repository
guarantees.