[MERGE] Add Bazaar Zen section to the User Guide

[Robert Collins]

On Fri, 2008-05-09 at 06:59 +1000, Ian Clatworthy wrote:


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

And surely no other systems commands have been introduced yet either :).
Why isn't something trivial like:

Revision Id's and Revision Numbers
----------------------------------

Revision Identifiers are globally unique identifiers for an individual
revision in bzr. They are long, cumbersome to type and are not
comparable to each other in any way. Revision id's are generated at
commit time (or for imports from other systems, at the time of the
import).

Bzr provides a much shorter identifier for revisions call a "revision
number'. Revision numbers are dotted decimal identifiers that trace a
path through the revision graph for a branch. Revision numbers are
generally shorter than revision ids, and (within a single branch) can be
compared with each other to get a sense of their graph relationship.
Revision Numbers are generated on the fly when 'log' or other commands
are executing, because they depend on the current branch tip.

Allocation of Revision numbers
==============================

[describe how they are allocated here]

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

Of course there are differences; however in terms of what 'log' outputs, we could drop revnos and go to a git style output with few if any changes deeper than: revspec.py, log.py & builtins.py. I think that that is pretty clearly a UI/presentation issue.

> > 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 can be specific about the confusion here - your example claimed to
show 'using push', but here you are describing it as being 'sending [gnu
diff?] patches to a upstream/gatekeeper'.

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

Well. I certainly appreciate that a 'workable lie' can be useful while
bootstrapping someones model of a system. But if we're doing that we
should tell people that we're working with analogies or simplifications,
because they will be treating this document as the last word on bzr
behaviour. If its deliberately wrong to aid learning, and they have to
infer that themselves, we're making the later transition to expert
somewhat harder.

BUT - I don't think we need such a mechanism here. Just not talking
about how other systems do it, and instead accurately and clearly
describing how bzr does it should be enough: a user of another system
will probably have enough conceptual framework to just 'get it' with
such a description, and a completely fresh vcs user will have something
accurate and complete with unambiguous terminology to refer to later.

-Rob

-- 
GPG key available at: <http://www.robertcollins.net/keys.txt>.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20080509/dac73a02/attachment.pgp