[MERGE] Add Bazaar Zen section to the User Guide

[Ian Clatworthy]

John Arbash Meinel wrote:
> Robert Collins wrote:

> | I'm sure that *I* don't want people to work in a particular way.
> | Bazaar's workflow features have come about by watching how people use
> | the tool and what behaviour seems to work well in different situations.
> |
> 
> I think what Ian has posted here is a relatively good exposition of how the
> Bazaar project views the revision graph. And it *does* encourage specific
> workflows. Because we view merge commits separately from mainline
> commits, we
> encourage people to think in those terms. (contrast that with mercurial
> and git,
> where all commits are "flattened" to a plain stream, which encourages a
> bit more
> history cleanup, because everyone sees all the commits in a row, etc.)

Thanks. As I mentioned on IRC, I really found this difficult to write given:

1. It arguably needs to be early in the manual so users
   aren't surprised/confused about the fact that revision numbers
   reflect the per branch views - and that's a feature, not a bug.

2. No bazaar commands have actually be introduced yet.

> | You also claim that bzr has internal differences vs git, darcs et al.
> | bzr and git are remarkably similar in regards to merge graph facilities;
> | only darcs is truely different.
> 
> Here, I agree with Robert. But I think it is mostly in the way Ian
> presented it.
> He claimed that the internals are different, but I would say it is
> probably our
> presentation layer. If you layered it into:
> 
> ~  Guts
> ~  UI Commands
> ~  Presentation
> 
> We are fairly similar in Guts and commandline to many systems. Probably
> similar
> enough that the differences are bothersome when switching between systems
> because they are otherwise so similar.
> The raw internal is just another DAG. It is our presentation of that DAG
> which
> differs from git and hg.

Fair enough. I think the differences are deeper than just presentation -
e.g. git ships around repos and branches are simply aliases of
revision-ids - but I'll s/internals/presentation/ in recognition of the
primary point I'm trying to get across.

> |
> | Secondly, your description of why to use merge vs push confused me; it
> | confused me because these things are orthogonal; if one uses solely push
> | & pull & commit it is not possible to resolve concurrent activity.
> | Pushing from feature branches does not prevent concurrency, and only
> | merge+commit can resolve concurrent activity across branches.
> 
> I agree there needs to be at least 1 merge, or possibly a rebase to make
> the
> "push" style work.

There does. I did realise that BTW. :-) My example shows the result of
sending a list of patches to an upstream/gatekeeper. I was implying
rebase+push without wanting to explain rebase. I'm really trying hard to
keep it *as simple as possible* here, so I'll try again in this bit.

> | I think the goal of explaining the core activities of working with
> | concurrent development is good; I think this document creates confusion
> | (or at least, it left me confused; and if I get confused by it, with my
> | detail understanding of the space, I'm really worried other folk will be
> | left utterly stumped).
> 
> I actually felt it was rather clear and straightforward. I would guess that
> knowing the details is what confused things.

Yes, too much knowledge can be quite annoying when reading documents
written for new users. :-)

Ian C.