[RFC] bzr-svn documentation updates...

[Eric Siegerman]

I realize your work isn't finished, so some of my detailed
complaints below might be due to that.  If so, my apologies.  I'm
piping up now because the main thrust of my comments is about the
broad focus of the document -- a thing better addressed early
than left till the detailed review stage.  Also, I haven't used
bzr-svn myself, only read some of the list threads about it
(curiosity about it was what led me to read your draft in the
first place).  There can be a benefit to that when reviewing
documentation, but it also means that I might have erred in my
facts.  If so, again, my apologies.

As I read the "Getting Started" section, I found myself thinking,
"this is precisely how I use bzr natively".  That leads me to
wonder whether bzr-svn docs are really the place for it.

I realize there's a tension here: the reason you started this
effort in the first place is that the bzr-svn docs are perceived
to be insufficient, but that one reason they don't say much is
that there's not a lot *to* say, because the way one uses bzr-svn
is, by design, pretty much the way one uses bzr without it.

But just redescribing the ways one uses bzr with *or without*
bzr-svn doesn't add very much information.  Indeed, one has to
intuit from all that tutorial the salient *new* fact, that "oh, I
guess bzr-svn works pretty much like bzr native.  Cool!".

Far better to simply state that fact, then spend most of the
document discussing the (presumably few) differences, as you do
in "Merging trunk to your feature branch".

The similarity could be emphasized by limiting the examples to
one or two that demonstrate direct interaction with the SVN
world.  E.g. after the "bzr checkout" example line, instead of
all the examples of vanilla bzr usage, just say something like:

	From here, you can use "trunk" very much as you would if it
	were a checkout of a native Bazaar branch.  You can branch
	from it, merge to it, commit, etc.

Then go into some detail about how a commit to the "trunk"
checkout affects the Subversion branch.  If you're committing a
merge, what happens to the nested revs in the Subversion world?
What other subtleties are there, that are specific to bzr-svn?
What about round-tripping?

Basically, what will surprise me, as a somewhat-experienced
Bazaar user, when coming to bzr-svn for the first time?  *This*
is what bzr-svn documentation should be spending its time on!


BTW, here's a place where this lack of focus appears to have
muddied the document itself.  In discussing sending a patch
upstream using "bzr send", you write:

> If the upstream project uses
> Bazaar to merge the patch, then the individual commits will all be
preserved.

But in the context of bzr-svn documentation, it seems pretty
likely that upstream *isn't* using Bazaar.  They must be using
Subversion, or the reader wouldn't be here in the first place,
right?

  - Eric