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

[Ian Clatworthy]

Stephen J. Turnbull wrote:
> I'm not Paul but I do have a few opinions here....
> 
> Ian Clatworthy writes:
> 
>  > Any reason why you prefer the Hg book to the Bazaar User Guide?
> 
> FWIW, having followed Arch development from the ArX fork to the Bazaar
> fork, I found the Hg book almost useless.  I already knew all that....
> As an extended tutorial, it doesn't cover as much of the generic side
> of revision control as the old Arch tutorial did, while as a manual
> ... well, no command is fully documented and most commands are
> undocumented; there's not even a reasonably complete listing of the
> important extensions.

We're missing that as well. I'm planning to add a chapter to the User
Reference documenting the standard extensions and a section to the User
Guide introducing the key ones for Bazaar: looms, bzr-svn, bzr-tools, etc.

> The BUG (oops), on the other hand, I found to be annoying with its
> continuous cheerful plugs for Bazaar.  It's almost smug: "distributed
> tree revisioning done right".  I think an official manual should take
> itself more seriously.  YMMV.  And somewhat hypocritical: although
> Arch (and implicitly git and Mercurial)

I'm never seen Git and Mercurial as being in the first camp with Arch. I
see them as being in the second camp with Bazaar and always have. The
tools in the first camp IMO are Arch, SVK, Monotone and Darcs, though
the latest version of Darcs is moving into the second camp now by the
sound of things.

Rather than risk the confusion here, I've combined all the DVCS tools
into a single generation in the patch submitted yesterday.

is deprecated as "not ready
> for prime time distributed tree revisioning"

I'm not sure where that quote is coming from. I don't ever recall making it.

> To me, Section 1.3 is out of place: at this stage the user either
> knows the initial workflow he wants to implement or doesn't know about
> workflows.  It takes up a lot of space and interrupts the flow of the
> introduction.  I would prefer a couple of examples of side by side
> implementations of a couple of tasks using CVS or svn vs. bazaar.  The
> diagrams in 1.3 are a distraction, because they are terrible as
> illustrations.  To figure out what's going on, you need to read the
> text and analyze the diagrams to understand the information flows.
> People who are pictorially oriented are likely to get rather confused
> IMO.

I'm open to removing or moving this section soon. For now, I want to
leave it because, warts aside, it frames the rest of the manual.

> Chapter 2 is excellent, except that I prefer section 1 to be replaced
> by "We assume you already have Bazaar properly installed, which you
> can test by issuing the command 'bzr --version'.  If that doesn't
> output something like
> 
> Bazaar (bzr) 1.3
> [spew elided]
> 
> Bazaar is easy to install.  See Appendix A."

I don't mind either way. I'll probably go with your suggestion but no
promises on timeframe - it's less important to me than other changes I
hope to make.

> Chapter 3 is also excellent.  Use of regexps in the .bzrignore should
> be mentioned, though, as people who know how to use them can get great
> advantage of them, especially in legacy projects with lots of ad hoc
> generated files.

Agreed.

> Chapter 4 again is very good.  One thing I noticed in Ch. 4, but is
> possibly true throughout the BUG, is that the concept of shared repo
> is a little imprecise.  Specifically, in many operations most dVCSes
> will follow parents until they find the meta-info.  But in creating
> new branches, is that true?  For example, what happens when you do:
> 
> bzr init-repo project
> cd project
> bzr branch bzr://central.org/project/trunk
> mkdir branches
> bzr branch bzr://outthere.com/project/wacko-branch
> bzr branch bzr://outthere.com/libwacko/libwacko
> 
> My intuition is that both wacko-branch and libwacko end up stored in
> the "project" repo, which is what you always want with wacko-branch,
> but it's not obvious if that's appropriate for the separately
> developed libwacko.

Did you mean to change into branches after the mkdir? As suggested, all
projects will share the repo. More diagrams in the Guide might help
explain this more clearly.

> Note that there's an ambiguity between "shared repo" meaning "stores
> revisions for many branches" and "shared repo" meaning "stores
> revisions for many users".  I don't recall ever being confused by it,
> but I wonder if a more naive user might.

Interesting. I have never thought of that but you make a good point. I
should clarify that via a note somewhere, say.

> Another thing I noticed in Ch. 4 (but may be more widespread) is a
> slight tendency to tell the user what she should want.  Eg, in
> discussing tools like gannotate (4.5.2), the BUG says "The GUI tools
> typically provide a much richer display of interesting information
> (e.g. all the changes in each commit) so they are often preferred over
> the text-based command by users."  I would put the period after the
> close paren and let the reader figure it out for herself.

Improved in the patch submitted yesterday.

> I'm not sure "Best Practices" is a good title for Ch. 7, which seems
> more like a "grabbag of goodies" than The Way The Pros Do It.  That
> is, by and large these are descriptions of features and how to invoke
> them, rather than explanations of when to use them and why (which is
> what "best practice" means to me).  Really, best practices are more
> suited to a wiki than the user guide.

I agree. It's more wishful thinking that reality now. It *will* include
best practices soon. :-)

Ian C.