[RFC] proposed user doc for nested trees

[Vincent Ladeuil]

In the following I use some abbreviations:

- NT: nested tree,
- CB: containing branch,

>>>>> "Ian" == Ian Clatworthy <ian.clatworthy at internode.on.net> writes:

<snip/>

    Ian> === added file 'doc/en/user-guide/nested_items.txt'
    Ian> --- doc/en/user-guide/nested_items.txt	1970-01-01 00:00:00 +0000
    Ian> +++ doc/en/user-guide/nested_items.txt	2009-05-07 15:51:06 +0000
    Ian> @@ -0,0 +1,410 @@
    Ian> +Nested items
    Ian> +============
    Ian> +
    Ian> +Introducing nested items
    Ian> +------------------------
    Ian> +
    Ian> +For many large projects, it is often useful to incorporate libraries
    Ian> +maintained elsewhere or to construct them from multiple subprojects.
    Ian> +While it is easy for a single user to setup a particular layout of
    Ian> +multiple branches by hand, the different branches really need to be
    Ian> +linked together if others are to reproduce the desired layout, and
    Ian> +if the relationships are going to be managed over time.
    Ian> +
    Ian> +Bazaar has good support for building and managing external libraries

s/has good support for/supports/. Support is a boolean.

    Ian> +and subprojects via a feature known as *nested items*.

s/a feature known//


<snip/>

    Ian> +Browsing nested branch history
    Ian> +------------------------------
    Ian> +
    Ian> +As nested branches have their own history, the ``log`` command shows
    Ian> +just the history of the containing branch. To see the history for
    Ian> +a nested branch, nominate the branch explicitly like this::
    Ian> +
    Ian> +  bzr log src/lib/sax
    Ian> +
    Ian> +Note however that ``log -v`` and ``log -p`` on the containing branch
    Ian> +will show what files in nested branches were changed in each revision.

s/./ of the containing branch/

    Ian> +
    Ian> +
    Ian> +Undoing nested branch changes
    Ian> +-----------------------------
    Ian> +
    Ian> +While committing in a containing branch will commit in nested branches

s/will/, bzr will/

    Ian> +by default, ``uncommit`` works in the opposite way, i.e. it recurses up
    Ian> +by default, not down. As explained above, if you make a change to a nested
    Ian> +branch like this::
    Ian> +
    Ian> +  edit src/lib/sax/parser.py
    Ian> +  bzr commit -m "fix bug #42 in sax parser"
    Ian> +
    Ian> +then two commits are actually done: one to the nested branch and one
    Ian> +to the current branch. The way to undo that commit pair is::

s/current/containing/

    Ian> +
    Ian> +  bzr uncommit src/lib/sax
    Ian> +
    Ian> +If you ``uncommit`` the current branch, then just that commit is undone

s/current/containing/

    Ian> +and the commit to the nested branch is left intact. The reason for this
    Ian> +behaviour is simple: Bazaar doesn't know whether the commits were done
    Ian> +as multiple steps or not and whether you want one or both commits undone.
    Ian> +In comparison, it doesn't have a choice if you uncommit the change made
    Ian> +to the nested branch. In that case, it *must* rollback the higher level
    Ian> +commit because the referenced tip revision no longer (logically) exists.

What do you mean here ? We face the problem every time we
uncommit after a push.

I expect that doing a 'bzr status' in the containing branch (CB)
will tell me that there are pending changes in the nested tree
(NT) if I do a 'bzr uncommit' in the nested tree.

commit followed by uncommit should remain a null
operation IMHO.

I can't imagine (yet) a workflow where I'd want to commit the
containing branch and the nested trees in a single atomic
operation.

The way I work so far when modifying both bzr and a plugin (for
the sake of the example let's imagine the plugin is the nested
tree).

When I need to merge/pull/commit the plugin, I do that
independently of the operations on bzr.

Once I'm satisfied with the NT, I commit it, *then* I commit the CB.

One way to guarantee that is to refuse committing in the CB if
there are pending changes in the NT.

That doesn't forbid having an option that will commit all nested
trees *and* the containing branch with a single command: uncommit
in that case can uncommit the nested trees for which a new
revision has been created by the commit (aka they appear in the
delta associated with the CB revision).

Now, do the nested trees share a repository or not ?

If they share the repository, it's easier to guarantee that the
nested tree revisions are present when handling the containing
branch revisions.

If they don't... the fun begins.

    Ian> +Updating nested branch locations
    Ian> +--------------------------------
    Ian> +

I need to think more about that, but roughly, it seems we need to
handle the branch.conf file (not only *one* location) for each
nested tree.

And *that* brings back the problem of which configuration values
should be propagated and which shouldn't. I'm afraid we can't
postpone solving that problem anymore.

'unpegged' nested branches went far above my head....

      Vincent