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

[Paul Moore]

On 26/03/2008, Russel Winder <russel.winder at concertant.com> wrote:
> I am not sure you actually need two books here, I think you can do with
> only one, but some careful curriculum and pedagogy is needed to avoid
> boring people who get DVCS and yet not losing those who don't.

Possibly. The major trick is to provide sufficient tutorial style
material for "those who don't get DVCS" while providing the detail
needed to act as a long-term reference. If you can't do that in one
book, then (in my view) you do need two.

Please note, I do *not* consider the Bazaar User Reference as the type
of reference material I want in a book. It's useful, but it's what I
get when I type "bzr help XXX". And I use the online help for that.
What I want in a reference manual is the supporting material that
explains which command I want, how the internals work (to give me my
mental "model"), that kind of thing. The stuff that's too much to
include in a "bzr help XXX" command :-)

>  I think you really do need a physical book as well as online documentation -- is
> anyone doing an O'Reilly, Manning, or Pragmatic Programmer's book on
> Bazaar?

I agree that Bazaar needs to have something that is specifically
written to be a physical book (with an index, etc etc). It doesn't
have to be published paper, though - a downloadable PDF would do fine
for me. But it needs to be written for hardcopy/print media, not for
online help content, or website content.

That's the key to the Mercurial book - it's a book first, and online
documentation second.

> Another "angle" is to show how to use DVCS as a way of working with CVCS
> -- in this case Subversion at the centre and Bazaar and Git at the
> leaves.  ( NB  Mercurial still has problems with this scenario I
> believe, which is good for Bazaar :-)  This means bzr-svn is critical!

I'd agree strongly with this. Interoperation with Subversion is likely
to be around for a long time yet. And the case where the Bazaar user
doesn't have Subversion commit rights is likely to be the most
important subcase of that.

But that's back to describing how people "should" implement a specific
workflow, and I'd still prefer to see more concentration on the
various tools available, and let people develop their own workflow.
DVCS workflow is new enough that there *are* no best practices yet. A
document with too much of the "distributed development with
centralised gatekeeper - do it like this" style adds to the (mildly)
patronising feel.

Once again, can I apologise for stressing the feel so much. I know the
intent was to communicate enthusiasm, but it really does come over
wrongly.

Paul.