[RFC] proposed user doc for nested trees

[Ian Clatworthy]

Aaron Bentley wrote:
> Thanks for your work, Ian.  I agree most of it.

That's nice to hear.

> This means distancing ourselves from the notion of 'by-value' nested
> trees.  I'm okay with that, but I want to make sure you understand that
> consequence.

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?

> 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. 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.)

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.

>> +In comparison, it doesn't have a choice if you uncommit the change made
>> +to the nested branch. In that case, it *must* rollback the higher level
>> +commit because the referenced tip revision no longer (logically) exists.
> 
> I don't think this is correct.  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.

> We might want to provide split --nested as a shortcut for split && join
> --nested.

Nice idea.

>> +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.

>> +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.

>> +When master locations are moved, it's the responsibility of the project
>> +administrators to update the locations stored with the central 'master'
>> +branch. Once that is done, they can send email asking users to run
>> +``bzr nested --delete-all`` followed by ``bzr pull``.
> 
> When branching from a branch with tree-references, I think bzr should
> create branches for each referenced branch in the containing tree's .bzr
> directory.  This is necessary so that subtrees are not considered
> out-of-date when the remote branch's reference branch is updated.
> 
> This section assumes that when the 'master' location's references go
> stale, everyone else goes stale too.  But with my proposal, everyone
> else will have local copies, so they will not be stale.  The 'master'
> location's reference branch locations would only be relevant when
> accessing the master branch itself.

I hadn't understood this. I'll revise it once we're consolidated this
piece of the puzzle.

>> +  bzr nested --no-pegged [DIR]
> 
> I don't agree with "one concept, one command", but even if I did, this
> doesn't seem like "one concept".  If anything, I would see this facility
> as an option on join.

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.

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. 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).

>> +The ``remove`` command deletes a nested branch when required like this::
>> +
>> +  bzr remove src/lib/ancientDB
>> +  bzr commit -m "delete ancientDB library - no longer used"
> 
> Actually, isn't that "remove --keep"?  This seems no different from any
> other file.

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

> 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.

Anyhow, I'm *really* pleased you agree with most of what I suggested. It
was obviously largely based on your work to date but I did exercise a
fair amount of poetic license in documenting how I'd like to see it
polished for end users. :-)

Ian C.