[RFC] proposed user doc for nested trees

[Aaron Bentley]

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

Ian Clatworthy wrote:
> Aaron Bentley wrote:
> I struggle to see much benefit in by-value nesting (when by-reference
> nesting is available). So I'm ok with that if others are. Am I missing
> some magic benefit re by-value nesting?

by-value nesting is available now and works now, either using bzr join
or the merge-into plugin.  I realize that you're not suggesting we
disable by-value nesting.  We would simply stop calling it nesting.

I do think it has benefits-- it is more compatible with other VCSes, and
is simpler to use.  Bazaar has, at times, incorporated code from other
projects (e.g. switch, the BaZing merge code, etc.), as has bzrtools.
Sometimes you want to preserve the other project as a separate entity,
but sometimes it makes sense to import it into your own project.

>> The other major change in this document is that you talk about nested
>> branches, not nested trees.  I find this really jarring.  Checkouts can
>> be nested, and the branches might not be nested at all.
> 
> I don't have a strong opinion here so I'm fine with using nested trees
> (or nested directories) instead of nested branches.

Great.  I propose reaffirming "nested trees", since that is already a
well-known name for the feature.

> The subtle point I
> was trying to get at was that the 'structure' exists in the branch and
> is there in a treeless branch say, i.e. it doesn't require a 'working
> tree' to be meaningful. (In comparison, filtered views really are
> working-tree local data.)

There is metadata at all three levels: branches, repositories and
working trees.  The goal of the feature is not to nest the branches, it
is to nest the WorkingTrees and RevisionTrees.

> If I get permission to change checkouts as Mark has requested, all
> checkouts will be lightweight and heavyweight checkouts will be created
> via branch --bind, so "nested branch" would not be ambiguous/misleading
> as it could be now. See http://bazaar-vcs.org/DraftSpecs/SimpleCheckouts.

I still disagree.  There should be no branches at all in the working
tree, so they won't be nested.

>> Nothing should happen in the containing
>> tree if you uncommit in the subtree.  We will tweak fetch to ensure that
>> all revisions referenced by tree references are copied around, even when
>> they are not in the ancestry the subtree's head.
> 
> Almost every reviewer so far has expressed an opinion about this
> particular topic so it clearly needs a bit more thought/analysis. We
> probably need to agree on some base principle like "commit/uncommit must
> be a no-op" and work backwards from there to get the right behaviour.

My principle is KISS :-)

>>> +There is limited support for specifying locations relative to the
>>> +location of the containing branch.
>> Limited how?
> 
> Hmm - that's badly expressed. It 'limited' versus the numerous (4)
> options Subversion 1.5 provides for relative locations. But *I* don't
> think we need anything more than what I've outlined, though others more
> experienced with Subversion's approach may disagree.

I suppose it is less flexible than svn's approach, but I think calling
it "limited" sets the wrong tone, if we think it's all we need.  We
should see about supporting scheme-relative URLs in general.  That would
be cool.

>>> +To delete the location of a nested branch::
>>> +
>>> +  bzr nested --delete DIR
>> I think it's an extremely bad idea to delete the location of a nested
>> branch-- bad enough that we should force users to edit
>> ".bzr/branch/references" if they really want to do that.
> 
> I considered suggesting "bzr nested --refesh DIR" to clear a local
> override. But that left the delete functionality as a gap. If we don't
> need/want delete, '--refresh' and '--refesh-all' seem cleaner to me.

I'm not sure we want anything at all (see
http://bazaar-vcs.org/NestedTreesDesign#sub-branches).  If we do, I
would be very conservative, and refresh only the locations that aren't
usable.  For a branch to be usable, it should:
 - exist in a good format
 - contain all the revisions that are mentioned in the tree-references
   of the containing tree.

Remember that a user's local copies may have revisions that are not
present in the upstream trees-- changing the references so that they do
not point at the user's local copies would usually be a bad idea.

> I hadn't considered that. Your suggestion makes sense to me. Whatever
> command we use for setting pegging we should also use for specifying
> nested files though.

I'm not sure what to do with nested files as a concept.  It seems to me
like supporting that would require supporting checkouts of single files,
but once we did, join could certainly be adapted to work with files.

> BTW, my expectation w.r.t. pegging is that it simply stores a special
> revision-id for that tree reference, say NULL_REVISION or some other
> magic value.

This is in line with what I discussed in my spec
http://bazaar-vcs.org/NestedTreesDesign#comments-on-differences
and I suggested using a reserved revision-id.

We could use "current:", which has thus far been used to represent the
current state of a working tree, or perhaps a new value of "head:"  I
think NULL_REVISION would not be a good choice, because it normally
means the first revision, not the most recent.

> The file mask/map also need to be stored in the inventory
> IMO (which implies yet another repo format unless something like
> "inventory item properties" are supported as suggested in
> http://bazaar-vcs.org/DraftSpecs/ExtensibleMetadata).

I didn't think you were proposing that we add such a thing right now.  I
thought that was a future work/wishlist kind of thing.

> If the library is no longer used, what value is there is keeping a copy
> of the nested branch on disk?

Being able to access old revisions.

>> I think a nice extension would be to allow subtrees to be missing and
>> behave as if they were present.
> 
> You'll need to explain this more. I'm not sure what you mean.

It's another way of handling the situation you described in your
"Virtual projects" section.  Instead of having a separate project for
the word processor, you create a nested nested tree that has on-disk
trees only for the code required by the word processor.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkoESoMACgkQ0F+nu1YWqI2oiACgiBoESv666zeLgN1lM7bQR41f
Vj4An2zsfE+uP74ZsTFyEmpxIyhqs+Lp
=mBbG
-----END PGP SIGNATURE-----