Fwd: [Python-Dev] Primer on distributed revision control?

[Ian Clatworthy]

Paul Moore wrote:
> On 25/03/2008, Paul Moore <p.f.moore at gmail.com> wrote:

> With regard to writing style, I agree with Steven Turnbull - the
> cheerful, nearly-smug style is fairly grating. (And the big, slightly
> rounded font used, plus the cheery cartoon-style diagrams, reinforce
> that impression, making it feel deliberate, rather than just an
> unfortunate turn of phrase).

Font selection, cartoon characters and text all came from different
sources FWIW, so if there is a conspiracy here, some evil genius is
masterminding it without the puppets being aware. :-) Seriously though,
I put forward a patch yesterday to partially address this. It's been
approved and submitted to PQM now.

> All of that is just style, and possibly reflects target audiences. I'm
> looking for something more like a good guide - not a tutorial, but not
> a reference manual. I much prefer written books, but am resigned to
> the fact that very little software comes with real paper manuals any
> more. But that's what I want - something that I can keep a printed
> copy on my desk to refer to.

I've raised bug #207557 accordingly.

> OK, enough on style, I'll try to describe my issues with content.
> 
> The section on core concepts is nice. But it has one glaring flaw,
> which is as much a flaw with Bazaar terminology as with the manual -
> none of the terms refer to anything *concrete*! I have a directory on
> my disk - what do I call it? The guide doesn't give me a name I can
> use[2]!

It's a control directory.

> Another particular issue I have is with the "Workflows" section. A
> large number of workflows are described, and yet *none* of them match
> how I want to work! The Mercurial book concentrates on telling me what
> tools I have, and leaving me to decide how to put them together.
> (There are just as many problems with doing things this way, but it's
> what *I* prefer).

Understood. I personally started learning Bazaar from the man-page which
I've since expanded to become the User Reference. I also like to know
exactly what a tool can do and go from there.

The thing to keep in mind though is that workflows are the "soul" of
Bazaar IMO. Bazaar is about staying out of your way and helping you get
things done, so the workflow models - not the DAGs underneath - are the
foundation from which I personally believe Bazaar ought to be explained
from. To me, development is about collaboration and I honestly want to
be focussing on that. My gripe with many other DVCS tools is that they
make collaboration first-and-foremost a DAG-management exercise. OK,
it's not quite that black-and-white but I value a simple process model
with an underlying complex data model (ala Bazaar) over a complex
process model with an underlying simple data model (ala Git).

> For what it's worth, the 2 ways I most often work
> are (1) a variation on personal use, where I'm using 2 unconnected
> machines (work and home) and a USB pen drive to sync between them
> (merging is a more common operation that way, as I regularly forget to
> sync before shutting down :-)) and (2) tracking an upstream project -
> often using Subversion rather than Bazaar - where I do not have commit
> access, and using my local Bazaar repository to develop patches for
> sending back upstream usually as simple patch files. I don't expect
> these workflows to be described, they are peculiar to me, but by
> describing workflows rather than tools, the Bazaar guide (a) gives the
> impression that my workflow is "less supported" and (b) doesn't give
> enough details on the individual pieces I'll need to consider to build
> my own workflow.

I think your workflows are common and ought to be included. I also think
we ought to be fixing (b). If you write up your workflows on a Wiki
page, I'll use that as the basis for additional User Guide content. I'm
sure you and others have plenty of associated tips and tricks that we
ought to be sharing more widely in an effort to distil best practices.

> As a result of the focus on "standard" workflows, chapters 3-6 all
> make me feel "no, this isn't the bit I'm looking for" - even if the
> actual text describes individual tools that would be useful to me!

I feel chapters 3 and 4 are fundamental and applicable to nearly every
Bazaar user. I probably need to make that clearer in the introduction.

> There is also a lack of lower-level detail. I know it's not
> necessarily reasonable content for a "user guide", and I'm not sure
> the placement of it in the Mercurial book is right, but the chapter on
> "Behind the Scenes" in the Mercurial book is really nice to have.

I'm happy to include this but in an appendix say. I found the early
placement in the Hg book jarring.

> I hope this is of some use.

Thanks. It takes time and thought to constructively review and critique
a 100 page manual. Much appreciated.

Ian C.