[RFC] proposed user doc for nested trees

[Aaron Bentley]

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

Thanks for your work, Ian.  I agree most of it.

Ian Clatworthy wrote:
> There are a few tweaks to the current UI suggested by this
> documentation. The main one is to to drop the 'reference' term and just
> use 'nested' everywhere I think it is needed.

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.

> Right now, --reference is a hidden option to join
> and the reference command is only days old

(and hidden)

> so I don't feel compelled to retain backwards compatibility here.

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.  We already talk
about trees in our documentation and UI, so I don't understand why we
should avoid talking about them here.

It also seems a bit odd to talk about "nested branches" versus "nested
files".  The normal distinction would be between files and directories.
 (And yes, I think I prefer "nested directories" over "nested branches".)

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

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

> +There is limited support for specifying locations relative to the
> +location of the containing branch.

Limited how?

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

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

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


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

I think a nice extension would be to allow subtrees to be missing and
behave as if they were present.

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

iEYEARECAAYFAkoDORUACgkQ0F+nu1YWqI1rtACeM8Q9LgOvpAbllKIfKiVI9p3c
/2cAn2IPf679aEM0vMsr7zyuFL/PfMCg
=F0Hy
-----END PGP SIGNATURE-----