Re: bzr repository ready?

[Eli Zaretskii]

> From: "Stephen J. Turnbull" <address@hidden>
> Cc: address@hidden,
>     address@hidden
> Date: Tue, 24 Nov 2009 10:33:50 +0900
> 
> Thanks for the review, Eli!

Thanks for writing that in the first place.

>  >    Compared to CVS, these branches are lightweight --- it doesn't cost much
>  >    to create them, as they're all sharing storage in the repository, and
>  >    they can't bother anyone else. However, there is one "weighty"
>  >    aspect: [etc, etc].
> 
>  > This is confusing and looks like a merge of 2 different narratives.
> 
> I'm not sure why you think that.

That was my way of trying to figure out what possible line of thinking
gave birth to that paragraph.  Forget it, I try explain the confusion
below in concrete terms.

>  > If the source tree is ``weighty'', then why are the branches
>  > ``lightweight''?
> 
> In Bazaar, the working tree and the branch metadata are basically
> independent of each other; they can even reside on different hosts,
> and branches can even exist without working trees.  Understanding this
> is fundamental to designing efficient workflows for Bazaar.

I'm not sure I understand this.  With the commands described on the
wiki, my understanding is that the history is in the `trunk' branch,
which is a mirror of (some) branches in the master repository, while
the source tree is in the development branches.  Is that true?

If this is true, then why does ``first bzr branch operation in a new
repository [...] take many minutes''?  It doesn't bring any source
files, only the history, right?  What brings the sources is the first
development branch you create, in our case with these commands:

    cd $DEVHOME/emacs
    bzr branch trunk/ quickfixes/

Right?

>  > Why is it important that there will be no build products in the
>  > tree? etc. etc.
> 
> That isn't obvious, even though I wrote "make bootstrap can take an
> annoying amount of time"?  I've fiddled with it a bit, but I don't
> know what to say.  If you still think it's confusing, I'll sleep on it
> and try again in a day or so, or maybe Karl or a 3d party can do
> something with it.

It's probably my confusion.  Let me take that paragraph apart and try
to show why it confuses the heck out of me.  I'm going to present a
narrative of my thoughts as I read the current text:

    Wiki: Compared to CVS, a Bazaar branch is lightweight -- it
    doesn't cost much to create one, as all branches in the repository
    are sharing storage

  Me: So far, so good...  Although it is not clear what storage is
  shared -- is it the sources that are common to all branches, the
  history, both?

    and they can't bother anyone else

  ??? what's this about? is it important? can it be deleted without
  sacrificing something important

    However, there is one "weighty" aspect: the source tree itself,
    which takes time to check out.

  okay, but when (at which time) does this weighty aspect rears its
  ugly head?  Is it at each "bzr branch" time?  Or does this happen
  only once?  If the latter, which one of the commands shown is the
  one that will cost me?

    Even more important, *there will be no build products in the
    tree.*

  "More important" than what?  Does this refer to the previous
  sentence or to the one before it?  And what's with "no build
  products in the tree" -- ain't I building Emacs in place?  Where
  will the products be, if not in the tree?

    make bootstrap takes an annoying amount of time.

  I knew that...

    That's why we recommend that for small changes you use and reuse a
    branch dedicated to such small changes.

  Does this "that's why" refer to the previous sentence about long
  bootstrap, or to everything else in this paragraph?

IOW, the logical thread of thought from one sentence to the next is
interrupted several times, and makes it hard to understand what the
text says and to discern facts from their explanation and the
recommendations.

I'm still not sure I understand the intent, but let me try to rewrite
this text assuming that I did understand:

  Bazaar allows all the branches in the repository to share storage,
  which makes the branches much more lightweight than CVS branches.
  However, it still takes time to checkout the source tree for each
  branch, and bootstrapping a new tree is annoyingly long.  That is
  why we recommend that for small changes you keep reusing the same
  ``quickfixes'' branch.  This way, once you bootstrapped the
  ``quickfixes'' branch once, the subsequent update, build, and commit
  steps of the update-edit-build-test-commit cycle will all be very
  fast, as long as you continue working in the same branch.

Note that I didn't put the "there will be no build products in the
tree" part anywhere, because my interpretation of the text (which is
probably incorrect or incomplete) didn't suggest any good place for
it.

>  > What about branches in the master repository?  Unless I'm missing
>  > something, the described workflows don't cover that.  What if I want
>  > to have my branch available from the upstream?
> 
> What about them?  The workflows don't cover them, and won't, until
> there's a policy permitting/regulating "sandbox" branches.  At this
> point, only maintainers need to worry about them.  This is not a
> document for maintainers (until Stefan, Yidong, or a release engineer
> they appoint asks for it).
> 
>  > (Release branches will need that, right?)
> 
> Yes, but AIUI people who create release branches are not the target
> audience of this document.

I thought the document targets maintainers as well.  Me, for example.

Thanks.