Re: bzr repository ready?

[Eli Zaretskii <eliz@gnu.org>]

> From: Karl Fogel <kfogel@red-bean.com>
> Cc: jearl@notengoamigos.org,  ian.clatworthy@canonical.com,  emacs-devel@gnu.org
> Date: Fri, 20 Nov 2009 14:22:28 -0500
> 
> My sympathies -- I came to bzr from the centralized-vc world too.  It's
> actually not that hard though.  You just have to separate the concept of
> "checkpoint my work" from the concept of "publish my work".  In
> centralized vc, these are unified in the "commit" command.  In Bazaar,
> "commit" means "checkpoint" and "push" means "publish" (roughly speaking).

(Actually, what I wrote about my ignorance was a lie, to some extent.
I did read Bazaar docs and related discussions before.  But I didn't
want to present only my personal problem, I wanted us to have a
tutorial that would be useful for others as well.)

> I've already written http://www.emacswiki.org/emacs/BzrForEmacsDevs.

Thanks.  I spent a couple of hours reading through it and related
docs.  Some comments:

 . The description starts with "bzr init-repo" followed by "bzr
   branch", but in fact all the discussions on the subject I saw till
   now recommend to "scp -r" instead.  It is unclear whether any of
   the first commands should be modified, replaced, or removed if the
   "scp -r" method is used.

 . http://doc.bazaar-vcs.org/latest/en/tutorials/centralized_workflow.html
   suggests to begin with "bzr whoami", but your description doesn't.
   Is it an omission, or "bzr whoami" is not required?  Any other
   useful configurations-related hints?

   Also, the above doc.bazaar URL uses the --trees switch to init-repo.
   What is its significance, and do we need to use it?

 . The suggested commands use some file names without describing their
   significance, if there is one.  Examples include trunk/ and dev/ --
   is there any reason to keep these precise names, or is it up to me?
   Also, the "cd" commands seem to indicate that all the directories
   should be under a single parent, like this:

          ROOT
               emacs
                     trunk
                     dev
                     SOME-TASKNAME

   Is this structure imposed by Bazaar or known conveniences, or is
   it just a suggestion, and the directories can be anywhere?

 . The considerations for starting a "task branch" as opposed to a
   lightweight branch are not clear.  The text talks about "multiple
   commits and rounds of feedback", but keeps silent about what does
   this "feedback" mean in practice.  More details are needed to make
   the "lightweight vs task branch" decision in practice.

 . The description of pushing local changes upstream say nothing about
   the ChangeLog files.  IIUC, unless I do something special, all my
   local log entries get to the upstream log files verbatim, and
   therefore (a) will be out of time-line (i.e. dates will not
   increase monotonically anymore), and (b) will include entries about
   intermediate changes we generally didn't want to see up until now,
   such as changes in functions that were subsequently deleted, or
   changes in functions that didn't exist on the trunk before local
   changes were pushed.  Unless there's some magic here that does TRT,
   I think we need instructions for this area.

 . The text says to update the mirror only _after_ pushing the local
   changes from the task branch and deleting that branch.  Is it not
   possible or advisable to update the mirror with partially pushed
   changes, while the task branch still exists?  (Use-case: while
   working on a new feature, I discover a bug in the existing code,
   and want to fix it without waiting for my final push.)

 . It's unclear whether building inside the mirror branch tree is okay
   or not.  For that matter, it's unclear whether the ``thing''
   created by "bzr branch" is just a simple directory tree, like the
   one created by "cvs checkout" (in which case one can build from
   within that tree), or something with more complex metadata, which
   makes building and editing in it undesirable.

 . There are still TBDs in the tutorial, in several important areas.
   The one for one-time contributors seems the most important one.

> > For each one of these, it would be enough to point to the relevant
> > sections of the existing bzr docs, no need to rewrite them, unless
> > some of the issues are mal-documented.
> 
> The above has a link to the Bazaar Users Guide, and other things.

I meant specific links to specific portions of the user guide, where
it describes in more details the individual parts of the workflow you
are describing.

> > In addition, some guidelines for selecting the right version of bzr
> > that should be installed, and if there are more than one that's
> > suitable, a short list of advantages and disadvantages of each of
> > them.
> 
> A version recommendation is already at the above link.

Yes, but it just says "1.17 or higher", to support some unnamed
features needed for Emacs.  Current versions of Bazaar are 2.0.2 and
2.1.0b1.  It would be good to have recommendations for the best
version since 1.17.

> > Finally, some guidance for users on Windows, if there are any issues
> > that need special attention (EOL format comes to mind, as well as
> > binary files, but maybe there's more).
> 
> That I can't help with (Windows-free since 1992), but there are plenty
> of Bazaar Windows users and an active user community in general.  See
> http://bazaar-vcs.org/ for details.

Are there some more focused pointers?  I couldn't find any
Windows-specific information on that page, or on first-level pages
linked from it.  What bothers me the most is the required setup of SSH
(since Bazaar evidently uses SFTP, or needs to use it to access the
master repository on subversions).  Any pointers for that?

Also, the merits and demerits of the two possible Windows installation
methods (either install Python and all the bzr dependencies manually,
then install bzr using a Python installer; or install the full bundle)
are not clear.  It sounds like the second one is faster and simpler,
but does not support easy uninstall when one wants to upgrade to a
newer version of bzr, is that right?