[RFC] proposed user doc for nested trees

[Stephen J. Turnbull]

Martin Pool writes:

 > So it is, but to me it doesn't seem that's what people are mostly
 > asking for with this feature.  They normally don't expect to make
 > commits spanning trees or to change most of the subtrees at all; they
 > just want an easy way to assemble and reproduce all the dependencies.

That's close but not quite true for me (but I do not claim to be
normal).  Two more use cases from XEmacs:

1. I was working on integrating neon support.  That is a project which
I have no interest in participating in, I dislike the coding style and
design, but it's a popular and usable WebDAV implementation.  It was
rare but not completely nonexistent for me to make changes to the neon
subtree.  Typically that was to add printf debugging to make sure that
XEmacs was passing what I thought it was passing.

Calling commit in the subtree to a local branch would have been ideal,
but in general I did *not* want those commits recorded as part of the
parent branch, which should consider those to be "outstanding local
changes" relative to the current version, including the upstream
version of neon I had originally checked out.  Of course push, but
also pull, were verboten.  I wanted an exact target to work to, and
only after I had it working for that did I want to deal with
variations in the API (which were frequent enough to be annoying).  In
fact over the period I was actively working on it, I did upgrade the
targeted neon revision twice.  But definitely I wanted to choose my
moment.

2. We have "unbundled" most Lisp libraries from the core which allows
users to pick and choose which libraries to install, and even to
install prereleases of some libraries alongside the released packages.
However, most users simply pick up the "SUMO" packages which contain
everything and the kitchen sink.  About half of these individual
packages continue to be maintained by the XEmacs project, and the rest
have "external maintainers", often upstream maintainers.

It is *very* important to us to avoid causing any annoyance to the
external maintainers (and some are quite vocal about any change, even
typo fixes).  Thus push is again not appropriate.  Committing to
several nested branches makes sense if a coordinated fix is involved,
but often enough the changes are actually unrelated and should be fed
upstream one by one.  I would definitely want a convenient way to
choose between recursive and non-recursive behavior, especially when
working on the package build infrastructure (such commits should not
normally pull in work on individual packages).  Finally, while it is
typically the case that debugging needs to be able to easily find
diffs between tip, current release, and previous release, indeed it
does make a lot of sense to make patches against tip.  Thus
"auto-pull" or "auto-update" for these nested branches makes a lot of
sense to me.