[RFC] bzr-svn documentation updates...

[John Szakmeister]

On Tue, Sep 15, 2009 at 10:04 AM, Eric Siegerman <lists08-bzr at davor.org> wrote:
> 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.

No worries.  I'd actually like to remove the broad focus... some of
that is left over content from the original document, and I think a
substantial portion of it should go.

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

True.  But I believe that folks that are looking to use bzr-svn are
probably new bzr users.

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

I don't intend to do a lot of that.  I agree, focusing on where the
differences are is where I plan spending most my time.

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

Good advice.

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

That's part of what I want discuss, but thanks for writing it down.

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

Absolutely.  FWIW, I didn't spend much time at all on the other stuff,
and don't intend to spend much more in it.  I do feel it's good to
have something, for the reason I stated above: someone new to bzr-svn
is likely to be new to Bazaar.

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

Who's to say that team isn't using bzr-svn against a svn repo?  But
you're right, that's probably atypical.

-John