[RFC] proposed user doc for nested trees

[John Arbash Meinel]

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


...

>     Ian> +Bazaar has good support for building and managing external libraries
> 
> s/has good support for/supports/. Support is a boolean.
> 

I've certainly had better and worse support. (Balance beam versus
10-foot wide bridge. Both "support" you, one is a whole lot better.)

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

...

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

So I would say that it should be possible to uncommit in a child branch,
and then commit that rollback to the parent branch. This is the same
operation as if you did a 'bzr pull -r -2', etc.

Certainly there is an argument as to whether commit and uncommit should
be recursive at all. Back when I was working with tla, I *really* wished
recursive commit was an option, since often I was making changes to 2
related but separate libraries. (And mostly it was just a pain to do
"for s in subdirs: commit".)


> 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 guess part of the question is that if we do a recursive commit, and
then uncommit, does it uncommit the sub-projects that it just committed?
I believe Ian's open question is the difference of:

bzr commit subdir1
bzr commit # commits everything and subdir2
bzr uncommit
# Can't tell that subdir1 was a separate commit, so either does both
# subdir1 and subdir2 or none.

Or as Stephen hinted, we could add a property to the revision, to
indicate whether they were combined or not...

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

If you make changes to a library, you want to update your program to
call the updated api.

You can argue that you get that because the containing tree commit is
atomic, so other people either have the older CB, and didn't get the
newer lib, etc.

Though things can get even more creative with:

metaproject/
  libs/
    libfoo/ # C library
    pylibfoo/ # Python wrapper
  progs/
    prog1/
    prog2/

At this point, 'prog2' certainly could depend on its sibling 'libfoo'.

Anyway, you can argue the atomicity is because of the containing tree,
but there is at least an argument that you want to maintain the version
of 2 subtrees in some form of 'lock-step'

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

I think you are missing the fact that if you 'commit in the plugin', and
then 'commit in the CB', the same change shows up "in the delta
associated with the CB revision", as if you did a recursive commit.

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

In Aaron's spec they do, because you have:

base/
 .bzr/
   branch/
   branches/
     NT1/.bzr/branch/
     NT2/.bzr/branch/
   checkout/
   [repository?]
  subdir/.bzr/
    branch/location => ../.bzr/branches/NT1
    checkout/

However, as part of the spec, we want to be able to do:

  bzr branch http://bazaar-vcs.org/bzr/bzr.dev

and have it also grab
  lp:bzr-svn

(for example)

However, I'm pretty sure Aaron is leaning towards forcing there to be
local branches for all subtrees. (So even if you did 'bzr co
- --lightweight .../bzr.dev', you would have a local branch for bzr-svn,
rather than a lightweight checkout of lp:bzr-svn.)

I'm not positive to that fact though, and I don't think he has mentioned
it in NestedTreeDesign yet.

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

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkoDVoYACgkQJdeBCYSNAAN6KACcDgepjYQEv00Jtpr+3zLwrGK8
VIsAn0pxMI0z14JxdRDrDMd0ySnlE7up
=VZut
-----END PGP SIGNATURE-----