[MERGE] Add Bazaar Zen section to the User Guide

[John Arbash Meinel]

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

Robert Collins wrote:
| On Thu, 2008-05-08 at 13:02 +1000, Ian Clatworthy wrote:
|> I recently gave an example on the mailing list that people found useful.
|> At the time, I promised I'd add it to the User Guide. This patch takes
|> the existing "Understanding Revision Numbering" section and combines it
|> with an expanded version of that example to create a new section called
|> "Bazaar Zen".
|>
|> Thanks to a trunkload of people for their insights and comments in
|> recent months about both Bazaar and its doc. At the risk of leaving out
|> many contributors, I hope this section captures some of those insights
|> from Matthieu Moy, Stephen Turnbull, John Yates, Eugene Wee, Matthew
|> Fuller, ...
|>
|> This is one of several TODO doc improvements I've been pondering for
|> some time. I hope to squeeze a few of them in before we ship 1.5 and
|> this one is likely to generate the most discussion so I'm submitting it
|> first. :-)
|
| Couple of things:
|
| 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.)


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

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

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

|
| (Your prose reads fine, and if you don't understand the core it seems
| clear; but its not, and that is I think the really potentially confusing
| part of it).
|
| Sorry,
| Rob
|


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

iEYEARECAAYFAkgjWjUACgkQJdeBCYSNAAPmiACgy9PFJ1Fp6WaANzxqhKq4NANH
nlYAoMetSzHA6poZLM2IqSJKNsp2i9Ks
=z4xK
-----END PGP SIGNATURE-----