Re: bzr repository ready?

["Stephen J. Turnbull" <stephen@xemacs.org>]

Richard Stallman writes:

 > I'm asking about how to use lightweight checkouts.  Someone
 > recommended them for people not writing lots of changes.

They're not in the BzrForEmacsDevs document, and if they appear, I
will *dis*appear and refuse to touch that document thereafter. ;-)

 > I got the impression that the lightweight checkout was recommended
 > because it avoids the need to make a local repository.

That's correct.  There is a better way, however, which is to use
a stacked branch.  Stacked branches

(1) retrieve only enough history to reconstitute the requested version
    of the source tree, and
(2) create new history locally (only locally) when "bzr commit" is invoked.

This has the following purposes:

(1) minimize the time and space cost of the initial branch operation,
(2) allow convenient updating to new upstream versions,
(3) allow people without commit privilege on Savannah to commit
    locally, which
(4) allows them to conveniently maintain both purely local hacks, and
(5) work intended for contribution back to the Emacs project.

It has certain defects:

(1) any operation (such as diff or log) that needs history before the
    initial version must go out to the upstream repo to get it.  Ie,
    it's slow and requires a network connection.

This mode of operation is recommended for beta testers, since they are
likely to start by just updating once in a while, but it imposes
minimum cost if they alter the sources: just commit the change
(locally).  It is *severely* deprecated for core developers.

 > The questions I've asked are based on that understanding.  The
 > answers I get seem to suggest the contrary,

These are experienced users explaining how they would use lightweight
checkouts to their own advantage.  Lightweight checkouts are neither
needed nor recommended for novice bzr users.  (Most of the people
describing how they would use checkouts have said the same thing.)

 > In other words, after doing 
 > 
 >    bzr branch URL_TO_UPSTREAM_EMACS_TRUNK
 > 
 > why not just go ahead and edit the files in the directory
 > for that branch?

There is no reason not to do that, except if you have commit
privileges in the upstream repository.  If you are going to push
directly to the upstream repository, then the roundabout method:

    cd WORKSPACE
    emacs
    bzr commit
    cd MIRROR
    bzr merge WORKSPACE
    bzr push

produces a much nicer "bzr log" output.  That is, the default view in
the upstream branch (and its mirrors) shows only the merge commits.
Each merge log describes the whole task (which might be something as
big as the emacs-unicode development and merge) in *one* log.  You can
also request a detailed output with "bzr log -n0", which lists the
entire history of a branch leading up the the merge.

This may not sound like much to you, but bzr fans consider this a
really important feature.

 > Is that true?  Once you do that command above, what is the state?
 > What can you actually DO with the branch at that point?

After "bzr branch URL_TO_UPSTREAM_EMACS_TRUNK emacs-work" *outside* of
a shared repo, you have in the emacs-work directory

(1) a full source tree as you would get with a CVS checkout, plus
(2) a .bzr directory containing branch configuration metadata (eg,
    project-wide bzr defaults and the source URL), plus
(3) a .bzr/repository directory containing the entire history of the
    upstream branch, including the full history of any branches merged
    into the upstream branch up to the point of the merge.

You may now unplug your computer from the Internet, and go to work,
performing all the operations that one can do with a single Bazaar
branch: commit, diff, log, branch, checkout, status (and some others).
Since you can commit, of course you can edit the files and manage
those changes with bzr.

You cannot push, pull, or update from the parent, of course (you just
pulled the plug!)

If you do "bzr branch URL_TO_UPSTREAM_EMACS_TRUNK emacs-work" *inside*
of shared repository *configured as recommended in the wiki*, you have

(1) a .bzr directory containing branch configuration metadata (eg,
    project-wide bzr defaults and the source URL), plus
(2) a ../.bzr/repository directory containing the entire history of the
    upstream branch, including the full history of any branches merged
    into the upstream branch up to the point of the merge.

Note the ".." in (2).  (In fact it could be more than one level of
parent, but that's not something that novice users need to do.)

To summarize:

 > Do you have to make a checkout from the branch in order to get
 > source files you can use?

If you do "bzr branch" outside of a shared repository, no.  You're
ready to go, but you should not push directly to the upstream branch.

If you do it inside of a shared repository, you need to do something
to reconstitute the source tree.  I recommend the procedure described
in the wiki, *not* a checkout, however.  In fact, I do not know how
the proponents of checkouts propose to preserve "nice" history with
the workflows they describe.

It's probably possible, but I don't know a straightforward recipe
that's less complex than the wiki recommendation.  If somebody does,
they should feel free to edit the wiki.