[RFC] proposed user doc for nested trees

[Aaron Bentley]

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

Martin Pool wrote:
> I liked the document a lot, both as something that can eventually
> become user documentation, and as a way to clarify the conversation
> about what we are going to merge into bzr.

I think it makes a lot more sense to start with the NestedTreesDesign
document which I updated at your request, and look at user-level
documentation afterward, as a supplement to it.

> I think this document needs a bit more detail about what's happening
> behind the ui, and so does this conversation if it's to move forward
> smoothly.

Is that detail that is missing from NestedTreesDesign?

> You cover it pretty well in some places by say what is or
> isn't stored, but I think for users to really understand this they
> need a model of what's recorded in the committed
> inventories/revisions, what's in the working tree, and what's in the
> branch/es.

The changes to the storage are described at
http://bazaar-vcs.org/NestedTreesDesign#data-storage

> The behaviour of 'bzr branch' on containing branches isn't explained
> by itself, only in passing in 'Virtual projects'.  From there we can
> infer when you branch, it brings across in the committed revisions
> references to the other branches, so we know those nested trees exist,
> and it seems that their working trees are created.

The behavior of branch is described at
http://bazaar-vcs.org/NestedTreesDesign#branching-from-a-nested-tree


> Are they branched
> from the branches in the source, or are they pulled from the same
> reference URL they originally came from?  (The second seems
> problematic if you're pushing to a server, because in general we don't
> assume that the server can go and make outgoing connections on your
> behalf.)
> 
> What happens if you have a branch with no working tree?

There is discussion of that in NestedTreesDesign.

> Presumably
> the fact that the nested trees were there is still present.

Yes.

> Is the
> data copied correctly in this case?

Yes.

>  Do they all go into the same
> repository?

If the containing tree's branch is part of a shared repo, yes.
Otherwise, no.


>  Will running 'bzr checkout' then reconstruct all the
> nested trees? (Perhaps obviously yes.)

Yes.

> One question possibly out of scope for this design: some other systems
> (like configmanager?) let you have the top level tree require creation
> of ./a and ./a/b without ./a needing to know anything about it.

This design assumes that if a contains b, then a depends on b.

> The only case I've seen for that is when people have a top-level tree
> which just does the assembly and nothing else.  It can probably be
> delayed; it may be worth noting as a restriction.

I have no idea how this design could be modified later so that the
presence of b was specified by the top-level directory, not by a.  If
that's an important feature, we should rethink this design now.

>> bzr branch --nested
> 
> I think "remember this branch in the parent" is more of an operation
> in its own right than someting just done by 'bzr branch'.

I was assuming branch --nested was essentially "bzr branch http://foo &&
 bzr join --nested foo".


> For example
> you might want to init a new nested tree, or you might already have an
> untracked nested branch constructed by some other means.  So why not
> have 'bzr join' or 'bzr add --nested' (though the second seems now
> discarded?)

We also have bzr join --nested.  I don't consider add to be explicit enough.

> I'd like, more for the sake of this discussion though it would also
> help users, to see how this would be shown by 'bzr status'.  If it
> recurses

http://bazaar-vcs.org/NestedTreesDesign#downwards-recursion specifies
that status is recursive.

> then it should show you the changes in the nested trees,
> obviously, but it also seems to need to show that the version of the
> nested tree in the parent is not what's in that branch.

You mean, in cases where the last-revision in the nested tree has
changed without the files changing?

> Ideally we would have one consistent rule for all commands as regards
> descent into nested trees.  If it's "they all recurse" that's great;

It is: http://bazaar-vcs.org/NestedTreesDesign#downwards-recursion

> Also, I think the code changes will be such that commands that aren't
> explicitly updated won't recurse; that's probably the only sane
> approach.  So that means that code in bzr that's not updated will
> default to not recursing, and code in other places (like bzr-gtk or
> qbzr) won't recurse either, at first.

True.  The issue is that we want to take small steps.  Before we
consider this feature 'beta', we will ensure consistent behaviour of
core commands:
http://bazaar-vcs.org/NestedTreesDesign#scope

And we can add support for additional commands incrementally.

> I think I'd rather be in the situation where they're all consistent
> (and not recursing) but some are lacking a useful option.

I would like to be consistent, but I think it's more important to decide
the correct behaviour.  Once that's decided, we can figure out how to
get to a consistent implementation of that behaviour.

>> nested branch locations are not tracked over time
> 
> I think we should say here where they are stored.  As non-versioned
> data in the branch, like tags?

Yes: http://bazaar-vcs.org/NestedTreesDesign#data-storage

>> bzr nested DIR LOCATION
> 
> So this seems to me a lot like the issue of managing the push, pull,
> etc default locations

No, it's managing the reference locations, which are the locations,
relative to the top-level branch, of the sub-branches.

> It seems like for nested branches you want to control the
> push, pull location for them too.

Yes, but only in the normal way.

> This section is actually raising a bit of a conceptual question for
> me: are you saying that the nested branches have their own tip
> pointer, or that they're really checkouts of branches held somewhere
> else

The working trees are checkouts, the branches are real branches:
http://bazaar-vcs.org/NestedTreesDesign#sub-branches

>> To delete the location of a nested branch: bzr nested --delete DIR
> 
> The text seems to imply that does not delete the directory, just
> forgets the location of its branch.  Are you then left with a checkout
> with no branch, in which you can't do anything much until you
> essentially rebind it?

No.

> I'm most concerned that this will come in when people have related but
> distinct branches that share file ids, eg if they both started by
> branching from a common template.  Or you might plausibly have
> libfoo1.1 and libfoo2.0 that share history.

See
http://bazaar-vcs.org/NestedTreesDesign#modelling-nested-trees-as-a-composite-tree

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

iEYEARECAAYFAkoJY5sACgkQ0F+nu1YWqI1UngCfQoGEgO/RyHhloK6rPH5bV63A
stsAnjTqsrL+2z8/BBi4vtb31Co6obQn
=r7ys
-----END PGP SIGNATURE-----