Basic Bazaar guide for Emacs hackers.

Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

[Posted this to help-emacs by accident.]

http://www.emacswiki.org/cgi-bin/emacs/BzrQuickStartForEmacsDevs

I know some of you are pushing hard for introducing complete and correct
dVCS practices among the Emacs developers. That is laudable but IMHO
unrealistic to expect since day one. So it is intended as a minimum
knowledge guide for not being left out. It is an appetizer too.

If you think that it is the wrong way to (not) enter dVCS, I'll delete
it or put a big warning sign at the beginning.

-- 
Óscar

Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Óscar Fuentes writes:

 > I know some of you are pushing hard for introducing complete and correct
 > dVCS practices among the Emacs developers.

What you are recommending is very easy for the individual developer
but makes for a messy history.  CVS *forces* you to either crap all
over the history, or to refrain from committing until the patch is
perfect.  dVCS gives you an alternative: commit frequently until done,
*then* push.

Please insert a big warning to explain that developers who choose this
workflow are making an antisocial choice of their own convenience
over more informative logs for the project.

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> Óscar Fuentes writes:
>
>  > I know some of you are pushing hard for introducing complete and correct
>  > dVCS practices among the Emacs developers.
>
> What you are recommending is very easy for the individual developer
> but makes for a messy history.  CVS *forces* you to either crap all
> over the history, or to refrain from committing until the patch is
> perfect.

The approach *suggested* (not *recommended*) on that page, makes things
worse than the current CVS practice?

> dVCS gives you an alternative: commit frequently until done,
> *then* push.

> Please insert a big warning to explain that developers who choose this
> workflow are making an antisocial choice of their own convenience
> over more informative logs for the project.

Fist of all, I shall note that what the page says is not intended to be
a permanent practice (although it works fine for quick fixes and small
changes). The page may be removed after a few months, once Emacs raises
and official policy for committing to the master branch.

So, if that practice does not turn things worse than now are wrt the VC
history, does it make sense to scare people away with words like
"antisocial"? If this is the case, I'll delete the page altogether. I
don't want to promote antisocial behavior on the emacs developers.

OTOH, have you considered the scenario consisting on people pushing
changes into the master branch without fully understanding how they
impact the history? I'm thinking on throwaway commits inadvertently
pushed, etc. This will be a transient effect, but so is the approach
described on the wiki page I wrote.

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Stefan Monnier]

>> I know some of you are pushing hard for introducing complete and correct
>> dVCS practices among the Emacs developers.
> What you are recommending is very easy for the individual developer
> but makes for a messy history.

As long as they only use CVS-style development, it shouldn't add any
mess to the history.


        Stefan

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Stefan Monnier writes:

 > > What you are recommending is very easy for the individual developer
 > > but makes for a messy history.
 > 
 > As long as they only use CVS-style development, it shouldn't add any
 > mess to the history.

Well, if you feel that way, I retract my statement, which was made on
the basis of how I would expect to feel in your shoes.

Re: Basic Bazaar guide for Emacs hackers.

[Richard Stallman]

    What you are recommending is very easy for the individual developer
    but makes for a messy history.

Could you explain what you mean by messy?  Objectively, which are the
characteristics you consider messy?  Knowing that, I could determine
whether I agree with you.

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

Richard Stallman <rms@gnu.org> writes:

>     What you are recommending is very easy for the individual developer
>     but makes for a messy history.
>
> Could you explain what you mean by messy?  Objectively, which are the
> characteristics you consider messy?  Knowing that, I could determine
> whether I agree with you.

I think Stephen is mixing things here.

People who work with dVCS often find convenient to commit to their local
branches from time to time before the feature is complete. This is most
convenient if you think on a complex feature that you divide on several
parts. As you implement each part, you commit to your local branch. Once
you completed the job, you send the changes upstream. This incorporates
your local commits on the upstream branch. Usually the rest of
developers are not interested on the steps you followed for implementing
your feature, so they want to see in the history:

  Implemented feature FooMatic

Instead of:

  Created stub functions
  Implemented the user interface
  Internal logic completed.
  Fixed a bug in foo-bar

With Bazaar you still can see that "inner history" if you ask for it,
but usually you don't care and seeing so many detail in the log would be
quite annoying. If you imagine several developers doing the same at the
same time the effect is even worse: the detailed inner history listed
above would be mixed with the commits of other developers. That's part
of the problem Stephen is talking about when he talks about "messy
history".

But the Emacs developers do not commit to CVS until the work is
finished. So if you keep committing only when the changes are ready for
mainline, the simple workflow I described on the wiki page is harmless
on this aspect.

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Óscar Fuentes writes:
 > With Bazaar you still can see that "inner history" if you ask for it,
 > but usually you don't care and seeing so many detail in the log would be
 > quite annoying. If you imagine several developers doing the same at the
 > same time the effect is even worse: the detailed inner history listed
 > above would be mixed with the commits of other developers. That's part
 > of the problem Stephen is talking about when he talks about "messy
 > history".

Yes.

Re: Basic Bazaar guide for Emacs hackers.

[Richard Stallman]

     > With Bazaar you still can see that "inner history" if you ask for it,
     > but usually you don't care and seeing so many detail in the log would be
     > quite annoying. If you imagine several developers doing the same at the
     > same time the effect is even worse: the detailed inner history listed
     > above would be mixed with the commits of other developers.

This is only an issue for changes large enough to have an inner
history.

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Richard Stallman writes:

 >     What you are recommending is very easy for the individual developer
 >     but makes for a messy history.
 > 
 > Could you explain what you mean by messy?  Objectively, which are the
 > characteristics you consider messy?  Knowing that, I could determine
 > whether I agree with you.

(1) VCS commit messages which are committed at the end of a protracted
    review tend to be less detailed and sometimes inaccurate,
    sometimes because they are not revised to reflect review,
    sometimes because the details are poorly remembered.  Conversely,
    the kinds of effort needed to keep accurate information in logs
    are somewhat reduced by a practice of frequent commits.  (In the
    workflow recommended by BzrForEmacsDevs, you get to have your cake
    and eat it too: "bzr log" by default shows the details of all the
    commits when used in the working branch, but only the summary log
    for the merge commit when used in mirrors of the trunk.)

(2) Medium-sized repetitive tasks (such as updating a bunch of
    function calls from an obsolete API to the recommended one) tend
    to occur in several commits, interspersed with commits from other
    tasks.

(3) Anything that can be considered a single task tends to get
    committed, even though a more global view would group it with
    other tasks.

(4) People tend to commit everything in their workspace, including
    unrelated typo fixes and small bugfixes.  Sometimes the additional
    changes aren't logged.  This is an easy mistake to make
    occasionally, even if you normally take care about it.

All of these can be ameliorated with discipline in a CVS-style
workflow; for most people it seems to require substantially less
effort to use feature branches to organize their work.

Re: Basic Bazaar guide for Emacs hackers.

[Eli Zaretskii]

> X-Spam-Status: No, score=-2.6 required=5.0 tests=AWL,BAYES_00,
> 	UNPARSEABLE_RELAY autolearn=unavailable version=3.1.0
> From: Óscar_Fuentes <ofv@wanadoo.es>
> Date: Sat, 28 Nov 2009 00:19:02 +0100
> 
> http://www.emacswiki.org/cgi-bin/emacs/BzrQuickStartForEmacsDevs

Thank you.

Re: Basic Bazaar guide for Emacs hackers.

[Richard Stallman]

    http://www.emacswiki.org/cgi-bin/emacs/BzrQuickStartForEmacsDevs

It is nice and simple.  I have one critique.  Someone said that the
term "checkout" for bound branches is deprecated.  It might be a good
idea to use the preferred term instead, and perhaps use a different,
not-to-be-deprecated command as well.

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

Richard Stallman <rms@gnu.org> writes:

>     http://www.emacswiki.org/cgi-bin/emacs/BzrQuickStartForEmacsDevs
>
> It is nice and simple.  I have one critique.  Someone said that the
> term "checkout" for bound branches is deprecated.  It might be a good
> idea to use the preferred term instead, and perhaps use a different,
> not-to-be-deprecated command as well.

I thought about this at the beginning and decided to do that way because
the document either uses undefined concepts known by CVS users or
defines the concepts that are new to them, as it does for the shared
repository.

Replacing

bzr checkout URL

with

bzr branch URL
bzr bind

will force me to explain what a Bazaar branch is and why it can be bound
or unbound, and thus would introduce us into the field of multiple
workflows, which is precisely what the document tries to avoid.

I don't see the `checkout' command deprecated or with its current
semantics changed anytime soon. This is a big change that would merit a
dot-zero version, and AFAIK that's not expected for a long time.

The terms are correct as per the "intended future" meaning, as we are
indeed creating a "bound branch" (which is absolutely orthodox). Using
the expression "heavyweight checkout" (or simply "checkout") is right
too, as any Bazaar user will recognize its meaning for a long time, and
even the term is profusely used on the documentation of the upcoming 2.1
version.

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Óscar Fuentes writes:

 > Replacing
 > 
 > bzr checkout URL
 > 
 > with
 > 
 > bzr branch URL
 > bzr bind
 > 
 > will force me to explain what a Bazaar branch is and why it can be bound
 > or unbound, and thus would introduce us into the field of multiple
 > workflows, which is precisely what the document tries to avoid.

I agree.  One caution I have is that in this case you probably should
also avoid mentioning offline work, which requires understanding what
"bound" means and either how to unbind or how to use the --local flag,
and the implications of that for future work when reconnected.

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

>  > will force me to explain what a Bazaar branch is and why it can be bound
>  > or unbound, and thus would introduce us into the field of multiple
>  > workflows, which is precisely what the document tries to avoid.
>
> I agree.  One caution I have is that in this case you probably should
> also avoid mentioning offline work, which requires understanding what
> "bound" means and either how to unbind or how to use the --local flag,
> and the implications of that for future work when reconnected.

The document has two parts: the first gives you everything you need for
commiting changes to Emacs' upstream and the second part hints at
possibilities ("see what you are missing") for motivating people to
learn more (and ends with a reference to your page). The second part is
intentionally vague and having half-cooked concepts there is perfectly
okay.

For the implications of committing offline, I was thinking on the
good-behaved CVS committer, as in the first part of the document. So
going offline does not mean here changing his commit criteria, but
simply deferring the sending of changes upstream. Do you think that this
is still problematic? (due to the pre-push merge, for instance) If yes,
I'll remove all explicit indications and leave just a note about the
possibility of committing offline.

Thanks for your comments.

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Óscar Fuentes writes:

 > For the implications of committing offline, I was thinking on the
 > good-behaved CVS committer, as in the first part of the document. So
 > going offline does not mean here changing his commit criteria, but
 > simply deferring the sending of changes upstream. Do you think that this
 > is still problematic?

I don't see a social workflow problem since everyone agrees that Emacs
committers have been well-behaved in the CVS context.  There's no
reason to suppose that will change in a CVS-like context just because
they're using Bazaar.

However, there are technical issues and some complexity in explaining
just what consequences offline commits have for your first commit
after reconnecting.  The behavior may be surprising to a new user.
Also, Stefan mentioned having had some issue with bound branches too.

 > (due to the pre-push merge, for instance) If yes, I'll remove all
 > explicit indications and leave just a note about the possibility of
 > committing offline.

How about:

    This workflow is designed with the assumption you'll be connected
    to the network whenever you want to commit.  It is possible to
    commit when offline, but if you need to do that frequently, first
    consider moving to a branch-based workflow as described in
    BzrForEmacsDevs.  If you still prefer this workflow, please ask;
    there are various methods, and which is best depends on your
    particular circumstances.

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

Hello Stephen.

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

>  > (due to the pre-push merge, for instance) If yes, I'll remove all
>  > explicit indications and leave just a note about the possibility of
>  > committing offline.
>
> How about:
>
>     This workflow is designed with the assumption you'll be connected
>     to the network whenever you want to commit.  It is possible to
>     commit when offline, but if you need to do that frequently, first
>     consider moving to a branch-based workflow as described in
>     BzrForEmacsDevs.  If you still prefer this workflow, please ask;
>     there are various methods, and which is best depends on your
>     particular circumstances.

I completely removed the reference to --local and simply explained that
is possible to commit off-line referencing your page and emacs-devel as
the authoritative sources for learning about that matter.

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Óscar Fuentes writes:

 > I completely removed the reference to --local and simply explained that
 > is possible to commit off-line referencing your page and emacs-devel as
 > the authoritative sources for learning about that matter.

Sounds good.

BTW, it's not really accurate to call it my page.  Most of the content
of the page is from Karl's edition, which in turn I think he said he
borrowed much from the Bazaar tutorials.

Re: Basic Bazaar guide for Emacs hackers.

[Richard Stallman]

    bzr checkout URL

    with

    bzr branch URL
    bzr bind

    will force me to explain what a Bazaar branch is and why it can be bound
    or unbound,

Not necessarily.  You can explain what the sequence of commands does,
and refer people elsewhere if they want to learn about those
individual commands.  You can explain what a "bound branch" does
and refer people elsewhere to learn about other kinds of branches.

    too, as any Bazaar user will recognize its meaning for a long time, and
    even the term is profusely used on the documentation of the upcoming 2.1
    version.

In that case, maybe it is fine to call this a "checkout".
I'm just going on what someone else said here.

Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

Óscar Fuentes <ofv@wanadoo.es> writes:
> [Posted this to help-emacs by accident.]
>
> http://www.emacswiki.org/cgi-bin/emacs/BzrQuickStartForEmacsDevs
>
> I know some of you are pushing hard for introducing complete and correct
> dVCS practices among the Emacs developers. That is laudable but IMHO
> unrealistic to expect since day one. So it is intended as a minimum
> knowledge guide for not being left out. It is an appetizer too.
>
> If you think that it is the wrong way to (not) enter dVCS, I'll delete
> it or put a big warning sign at the beginning.

The more options we offer, the more confused people will be.  Also, the
more different workflows developers use, the more difficult it will be
for us to support each other.

Can we please not fall into this tar pit? :-)

I hate to say this, knowing how hard you must have worked on it, but I'm
worried the document will do more harm than good in the long run.  IMHO,
either delete it or maybe just put some kind of warning sign at the
beginning, linking to [1].

Coming from the Subversion-and-CVS world, I needed less than a day to
get used to the Bazaar/distributed way of working.  It just isn't that
hard.  Anyone who works on Emacs can get used to it in about that amount
of time.  Sure, there will be little questions here and there, but the
main loop documented at [1] will be comprehensible to all.

No one here is saying we should introduce "complete and correct dVCS
practices...since day one".  I *am* saying that it is completely
reasonable to expect Emacs developers to read and understand [1], and to
work that way from that point forward, until they understand Bazaar well
enough to vary their workflow as they wish.

There's nothing wrong with the content of BzrQuickStartForEmacsDevs.
It's just that if Emacs developers start doing things that way too, then
the total support burden on the community goes up.  We should not
stimulate that situation if we can avoid it.

Best,
-Karl

[1] http://www.emacswiki.org/emacs/BzrForEmacsDevs

Re: Basic Bazaar guide for Emacs hackers.

[Lennart Borgman]

On Mon, Nov 30, 2009 at 3:05 AM, Karl Fogel <kfogel@red-bean.com> wrote:
>
> There's nothing wrong with the content of BzrQuickStartForEmacsDevs.
> It's just that if Emacs developers start doing things that way too, then
> the total support burden on the community goes up.  We should not
> stimulate that situation if we can avoid it.

Interesting. In science someone (very familiar) said "make it simple,
but not too simple".

IMO the burden of not making it simple has often been neglected in
free software development. It is like it did not matter. But I think
it does in many ways. And it is often very complicated to understand
what it too simple and what is not enough simple.

Like here.

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Lennart Borgman writes:

 > Interesting. In science someone (very familiar) said "make it simple,
 > but not too simple".

And Saunders Mac Lane, who is not at all familiar -- except to some of
you, I suspect -- said "[G]ood general theory does not search for the
maximum generality, but for the right generality."

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

Karl Fogel <kfogel@red-bean.com> writes:

> Óscar Fuentes <ofv@wanadoo.es> writes:
>> [Posted this to help-emacs by accident.]
>>
>> http://www.emacswiki.org/cgi-bin/emacs/BzrQuickStartForEmacsDevs
>>
>> I know some of you are pushing hard for introducing complete and correct
>> dVCS practices among the Emacs developers. That is laudable but IMHO
>> unrealistic to expect since day one. So it is intended as a minimum
>> knowledge guide for not being left out. It is an appetizer too.
>>
>> If you think that it is the wrong way to (not) enter dVCS, I'll delete
>> it or put a big warning sign at the beginning.
>
> The more options we offer, the more confused people will be.

... unless each person finds the option adequate for him among the
available ones.

What is confusing, IMHO, is to provide several options with similar
degree of complexity, and that demand from the user to apply new
concepts and see himself on not-yet-experienced scenarios for deciding
which one is the right one for him.

> Also, the more different workflows developers use, the more difficult
> it will be for us to support each other.

Forcing developers to use workflows that they do not understand creates
support requests. Forcing developers to use workflows that they find
gratuitously complicated scares them away.

> Can we please not fall into this tar pit? :-)
>
> I hate to say this, knowing how hard you must have worked on it, but I'm
> worried the document will do more harm than good in the long run.  IMHO,
> either delete it or maybe just put some kind of warning sign at the
> beginning, linking to [1].

What's exactly the reason for the warning? Is it like they will damage
the Emacs project if they choose that workflow? I don't think so. Maybe
they damage themselves by not using a more effective workflow for their
specific needs, but that is implicit all along the document and, really,
it is up to them to pick wathever they find appropriate. And, actually,
that workflow is perfectly fine for occassional contributors or people
who work on simple tasks like quick-fixes.

The document is a sort of "this is the minimum you need to know, but
keep reading if you want more." Either the developer thinks that the
workflow is adequate and he keeps contributing or he wants more and goes
to your document. What's wrong with that?

> Coming from the Subversion-and-CVS world, I needed less than a day to
> get used to the Bazaar/distributed way of working.  It just isn't that
> hard.

Funny. I come from CVS and Subversion too, but learning dVCS took me
several days of highly motivated effort to re-program my mind.

Maybe the difference among you and me is that I was not a Subversion
developer and version control concepts were not in my mind all day
long. I'm pretty sure that when you started your bzr usage all its
underlying concepts were already familiar to you.

> Anyone who works on Emacs can get used to it in about that amount of
> time.  Sure, there will be little questions here and there, but the
> main loop documented at [1] will be comprehensible to all.
>
> No one here is saying we should introduce "complete and correct dVCS
> practices...since day one".  I *am* saying that it is completely
> reasonable to expect Emacs developers to read and understand [1], and to
> work that way from that point forward, until they understand Bazaar well
> enough to vary their workflow as they wish.

You are overestimating the Emacs developers. Not their intelligence or
knowledge about CS. You are overestimating their commitment to the
project.

AFAIK most Emacs committers can't be considered "regular"
contributors. All of them are volunteers. They appear, do some bug
fixing, add features or even create a new framework, but then they
vanish for months or years.

Expecting from them to learn a fringe tool like Bazaar on certain
"recommended" way and then not having to re-learn it when they come back
after three months is unrealistic.

Expecting from somebody, who simply wants to correct the bug that annoys
him so much, to learn a new tool together with a series of new concepts
and practices for creating a simple patch, is raising the entry barrier
quite a bit.

> There's nothing wrong with the content of BzrQuickStartForEmacsDevs.
> It's just that if Emacs developers start doing things that way too, then
> the total support burden on the community goes up.  We should not
> stimulate that situation if we can avoid it.

The intent of the document is to *lower* the support burden. If a CVS
committer (or anyone with CVS or Subversion experience) has problems
putting into practice what's described there, then your guide will be
absolutely incomprehensible for him.

I have no problem at all deleting the document if it damages the
transition to Bazaar. But so far, your reasons for doing it are not
convincing at all to me and just demonstrates a misunderstanding of the
demography of Emacs and their current VC practices.

All this said with respect and appreciation.

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

Óscar Fuentes <ofv@wanadoo.es> writes:
>> The more options we offer, the more confused people will be.
>
> ... unless each person finds the option adequate for him among the
> available ones.
>
> What is confusing, IMHO, is to provide several options with similar
> degree of complexity, and that demand from the user to apply new
> concepts and see himself on not-yet-experienced scenarios for deciding
> which one is the right one for him.

I agree, we should not do that.  Are we doing that?  My intention has
always been to recommend

  http://www.emacswiki.org/emacs/BzrForEmacsDevs#RegularContributors

as the place to start.

> I have no problem at all deleting the document if it damages the
> transition to Bazaar. But so far, your reasons for doing it are not
> convincing at all to me and just demonstrates a misunderstanding of the
> demography of Emacs and their current VC practices.
>
> All this said with respect and appreciation.

Understood.

I'm beginning to realize it doesn't matter.  Once Emacs switches, we'll
see what people really need, and then we'll provide it.  So I'm not
going to worry about it.  We'll switch, and there will be grumbling, and
then it will be fine.  IMHO, we already have prepared all the
documentation we can in advance.

Best,
-K

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Óscar Fuentes writes:
 > Karl Fogel <kfogel@red-bean.com> writes:

 > > The more options we offer, the more confused people will be.
 > 
 > ... unless each person finds the option adequate for him among the
 > available ones.

The problem is that people just don't do that when faced with several
options.  They pick the best features of each and expect the
application to provide all of them.  Or they don't like something so
they tweak it.  Then they get confused.

 > I have no problem at all deleting the document if it damages the
 > transition to Bazaar. But so far, your reasons for doing it are not
 > convincing at all to me and just demonstrates a misunderstanding of the
 > demography of Emacs and their current VC practices.

On the other hand, how many VCS transitions have you managed for
Emacs-sized projects?  I've done two so far.  I can say from
experience the cost of support is not polynomial in extra workflows
during the transition.

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

>  > I have no problem at all deleting the document if it damages the
>  > transition to Bazaar. But so far, your reasons for doing it are not
>  > convincing at all to me and just demonstrates a misunderstanding of
>  > the demography of Emacs and their current VC practices.
>
> On the other hand, how many VCS transitions have you managed for
> Emacs-sized projects?  I've done two so far.  I can say from
> experience the cost of support is not polynomial in extra workflows
> during the transition.

Okay. Your experience trumps over my reasoning. Page deleted.

But from now on I don't feel obliged to help supporting those who think
that they have better things to do than learning a new way of doing
something that worked fine for the last 20 years :-)

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

Óscar Fuentes <ofv@wanadoo.es> writes:
>>  > I have no problem at all deleting the document if it damages the
>>  > transition to Bazaar. But so far, your reasons for doing it are not
>>  > convincing at all to me and just demonstrates a misunderstanding of
>>  > the demography of Emacs and their current VC practices.
>>
>> On the other hand, how many VCS transitions have you managed for
>> Emacs-sized projects?  I've done two so far.  I can say from
>> experience the cost of support is not polynomial in extra workflows
>> during the transition.
>
> Okay. Your experience trumps over my reasoning. Page deleted.
>
> But from now on I don't feel obliged to help supporting those who think
> that they have better things to do than learning a new way of doing
> something that worked fine for the last 20 years :-)

Hmm.  I think we have been editing simultaneously!

Here's what I just did:

  * Removed all the alternate scenarios and stacked-branches talk from
    http://www.emacswiki.org/emacs/BzrForEmacsDevs, leaving just the one
    workflow for regular contributors.  I hope this simplifies the page
    a lot, and makes it clear that it is intended to give a single,
    recommended workflow.

  * For those alternate scenarios, we now refer out to a new page:
    http://www.emacswiki.org/emacs/BzrForEmacsCasualDevs, which strongly
    recommends people to use the regular workflow, but describes a
    couple of alternate ways for those who really want that.  Because it
    still makes it clear that we recommend the "regular contributor"
    workflow, I think this will not lead to confusion.

  * On http://www.emacswiki.org/emacs/BzrQuickStartForEmacsDevs, I've
    moved the recommendation to try the "regular contributor" workflow
    (i.e., BzrForEmacsDevs) to the top, and strengthened it.  Oscar, I
    hope that was okay, and that you feel the wording there is accurate.
    If not, please tweak.  I did my work in the wiki instead of the
    mailing list only because that seemed the easiest way to communicate
    my edits, not because I meant them to be the final word.

I think our documentation is mostly consistent and non-confusing now.

We have three pages, but two of them point clearly to BzrForEmacsDevs as
the recommended workflow, and that page refers out to the other two
where appropriate.  We can also manually point a person to either of
those other two if and when that person balks at using BzrForEmacsDevs
(for lack of time or whatever reason).

So when we do the switchover, if we point to

  http://www.emacswiki.org/emacs/BzrForEmacsDevs

as the place to start, that should work, and will nudge people toward
adopting a dVCS way of working from the start.  But those who don't want
that have other options prepared for them.

Does this sound sane?

Continued improvements to any of the docs welcome, of course.

-Karl

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

Karl Fogel <kfogel@red-bean.com> writes:

[snip]

>> Okay. Your experience trumps over my reasoning. Page deleted.
>
> Hmm.  I think we have been editing simultaneously!

You resuscitated the page 25 minutes after I deleted it.

> Here's what I just did:
>
>   * Removed all the alternate scenarios and stacked-branches talk from
>     http://www.emacswiki.org/emacs/BzrForEmacsDevs, leaving just the one
>     workflow for regular contributors.  I hope this simplifies the page
>     a lot, and makes it clear that it is intended to give a single,
>     recommended workflow.

[snip]

That's good idea. The shorter the document is, the less daunting it
looks. Moving alternate workflows to other page instead of deleting them
was good idea too, IMHO, although I guess that deleting them would be
more appropriate from Stephen's POV.

>   * On http://www.emacswiki.org/emacs/BzrQuickStartForEmacsDevs, I've
>     moved the recommendation to try the "regular contributor" workflow
>     (i.e., BzrForEmacsDevs) to the top, and strengthened it.

[snip]

Your changes looks okay to me. Nevertheless, if you still think that
BzrQuickStartForEmacsDevs will create more problems than solutions on
the transition, go ahead and send it back to the heaven of the wiki
pages.

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Your description sounds sane to me.  I'm going to be preparing for a
business trip and start of classes, so if you want me to review
somethingbefore the weekend, ping me directly (I won't be looking at
emacs-devel for a couple of days, starting now :-).

Re: Basic Bazaar guide for Emacs hackers.

[Eli Zaretskii]

> From: Karl Fogel <kfogel@red-bean.com>
> Date: Mon, 30 Nov 2009 00:03:59 -0600
> Cc: emacs-devel@gnu.org
> 
> Here's what I just did:

Thanks.

> Continued improvements to any of the docs welcome, of course.

I fixed one or two factual inaccuracies and slightly improved wording
in a couple of places.

What's below are random stylistic and methodological comments.  Feel
free to do anything you want with them, including nothing at all.

 . The page is biased towards contributors who don't have write access
   to the Emacs repository.  Notably, it gives almost all examples
   using the HTPP URL, not the SFTP one.  Sometimes it mentions the
   SFTP method, sometimes it does not.  It could be a better idea to
   give both variants for each command.

 . A Unix-like system is assumed without any notice to that effect.
   Some commands will not work on Windows without subtle changes.  For
   example,

    echo "public_branch = http://bzr.savannah.gnu.org/r/emacs/trunk" >> .bzr/branch/branch.conf

   will not do what you mean with the `echo' that it built into the
   Windows shell.  Maybe someone could add footnotes with Windows
   equivalents, where applicable (in this case, either remove the
   quotes or use the ported GNU `echo').

 . The single-level sectioning is not the best one in this case,
   because the page actually has 5 top-level sections, which I would
   call Intro, Getting Started, One-Off Change, Feature Branch,
   Resources; and some of these have sub-sections.  Presenting them as
   a single-level document makes it harder to grasp the outline of the
   narrative.  Suggest to have 2 levels of sections, not one.

 . The "Overview of the Bazaar work routine" is too detailed, IMO, and
   thus unnecessarily longish.  We will be explaining all the details
   in a moment, so I think only the main points should be left in this
   overview.

 . "Other Resources" should be at the beginning.  Someone who looks
   for a CVS-like way of doing things should not be required to read
   through such a long document to find the alternatives near the end.

Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

Eli Zaretskii <eliz@gnu.org> writes:
>> Continued improvements to any of the docs welcome, of course.
>
> I fixed one or two factual inaccuracies and slightly improved wording
> in a couple of places.

Thank you!

> What's below are random stylistic and methodological comments.  Feel
> free to do anything you want with them, including nothing at all.
>
>  . The page is biased towards contributors who don't have write access
>    to the Emacs repository.  Notably, it gives almost all examples
>    using the HTPP URL, not the SFTP one.  Sometimes it mentions the
>    SFTP method, sometimes it does not.  It could be a better idea to
>    give both variants for each command.

Hmmm.  Good point -- I'll take a look and see what I can do.  If
anything, it should be biased toward SFTP and mention HTTP as an
alternate method.

>  . A Unix-like system is assumed without any notice to that effect.
>    Some commands will not work on Windows without subtle changes.  For
>    example,
>
>     echo "public_branch = http://bzr.savannah.gnu.org/r/emacs/trunk" >> .bzr/branch/branch.conf
>
>    will not do what you mean with the `echo' that it built into the
>    Windows shell.  Maybe someone could add footnotes with Windows
>    equivalents, where applicable (in this case, either remove the
>    quotes or use the ported GNU `echo').

Also a good point.  I haven't used Windows for almost 18 years now, so
I'll just put in notes that it's Unix-centric.

>  . The single-level sectioning is not the best one in this case,
>    because the page actually has 5 top-level sections, which I would
>    call Intro, Getting Started, One-Off Change, Feature Branch,
>    Resources; and some of these have sub-sections.  Presenting them as
>    a single-level document makes it harder to grasp the outline of the
>    narrative.  Suggest to have 2 levels of sections, not one.

I can do that (is there any reason you didn't just make the change,
though?).

>  . The "Overview of the Bazaar work routine" is too detailed, IMO, and
>    thus unnecessarily longish.  We will be explaining all the details
>    in a moment, so I think only the main points should be left in this
>    overview.

Will take a look and adjust accordingly.

>  . "Other Resources" should be at the beginning.  Someone who looks
>    for a CVS-like way of doing things should not be required to read
>    through such a long document to find the alternatives near the end.

I was already planning to move the "quick start" links to the beginning,
along with some explanation.  The other other resources can stay where
they are, I think.

Thanks for the review, Eli.

-K

Re: Basic Bazaar guide for Emacs hackers.

[Eli Zaretskii]

> From: Karl Fogel <karl.fogel@canonical.com>
> Cc: ofv@wanadoo.es,  emacs-devel@gnu.org
> Date: Mon, 30 Nov 2009 13:37:06 -0600
> 
> is there any reason you didn't just make the change, though?

These are largely a matter of methodology: how to present this subject
to Emacs developers.  With all the differences of opinions on issues
like this between myself and almost everybody else that we've seen
lately here, I lost confidence that such changes will be welcome.

> >  . "Other Resources" should be at the beginning.  Someone who looks
> >    for a CVS-like way of doing things should not be required to read
> >    through such a long document to find the alternatives near the end.
> 
> I was already planning to move the "quick start" links to the beginning,
> along with some explanation.  The other other resources can stay where
> they are, I think.

In that case, at least mention right at the beginning that whoever
looks for something like that will find it near the end.

Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

Eli Zaretskii <eliz@gnu.org> writes:
>> is there any reason you didn't just make the change, though?
>
> These are largely a matter of methodology: how to present this subject
> to Emacs developers.  With all the differences of opinions on issues
> like this between myself and almost everybody else that we've seen
> lately here, I lost confidence that such changes will be welcome.

Oh, those differences have all been about what overall direction to
recommend to developers, which is a larger issue that's not really about
any individual document's structure.

AFAIK, everyone has welcomed organizational edits made to any page --
certainly I have, and so have Óscar and Stephen.  Please don't be afraid
to edit.  (But I'll take care of this one, since I'm already doing other
stuff on the page.)

-Karl

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Eli Zaretskii writes:

 >  . The page is biased towards contributors who don't have write access
 >    to the Emacs repository.  Notably, it gives almost all examples
 >    using the HTPP URL, not the SFTP one.

That's right, but the reason I left it that way was not "committers"
vs. "others".  It's "URLs we are almost sure will work" vs. "URLS we
hope will be replaced by much better schemes".  If at all possible, we
want the SFTP URL to be replaced by bzr+ssh, but that does not work at
all right now.  My logic is that as it stands, the reader who doesn't
remember the committer URL must go back to the beginning, where she
will see the warning about possibly changing URLs.

@RMS: Is there no chance that you will intervene and ask the Savannah
admins to increase the priority of bzr+ssh?  This is extremely
important to the uptake of Bazaar on Savannah.  With dumb transports
like HTTP and SFTP, frequently network transfers of 25MB have been
observed in the process of committing a tiny (~10 lines) patch,
because a whole pack (essentially, a zip file full of diffs
representing revisions) gets transferred from the local system to the
upstream master.  With a bzr server, only the diff need be sent, and
the pack is rewritten on the upstream master's host.  This affects all
committer workflows, and IIRC locks the repository so that other
committers cannot write (AFAIK it's still readable, but of course
readers will get stale data).

But the concerns of the Savannah hackers are valid.  Although
discussion on bazaar@canonical.com indicates that their security
analysis is incorrect, they must convince themselves that is true, and
that is not costless.  Only you have the stature to increase the
priority of that work.

 >  . A Unix-like system is assumed without any notice to that effect.
 >    Some commands will not work on Windows without subtle changes.  For
 >    example,
 > 
 >     echo "public_branch = http://bzr.savannah.gnu.org/r/emacs/trunk" >> .bzr/branch/branch.conf

In this particular case AFAIK you don't need the quotes on Unix either.

 >  . "Other Resources" should be at the beginning.  Someone who looks
 >    for a CVS-like way of doing things should not be required to read
 >    through such a long document to find the alternatives near the end.

You are welcome to edit it that way if you want.  I believe you would
certainly have RMS's support in doing that.  I'm not going to play
"last patch wins" if you do, and I don't think Karl will either.

Re: Basic Bazaar guide for Emacs hackers.

[Richard Stallman]

      * On http://www.emacswiki.org/emacs/BzrQuickStartForEmacsDevs, I've
	moved the recommendation to try the "regular contributor" workflow
	(i.e., BzrForEmacsDevs) to the top, and strengthened it.

You are pushing too hard for people to use the more complex dVCS
workflow.

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Óscar Fuentes writes:

 > > On the other hand, how many VCS transitions have you managed for
 > > Emacs-sized projects?  I've done two so far.  I can say from
 > > experience the cost of support is not polynomial in extra workflows
 > > during the transition.
 > 
 > Okay. Your experience trumps over my reasoning. Page deleted.

I'm going to keep a copy (unless my browser has crashed in the
meantime ;-) and integrate some of it into the section of our page on
stacked branches.  Is that OK with you?

 > But from now on I don't feel obliged to help supporting those who think
 > that they have better things to do than learning a new way of doing
 > something that worked fine for the last 20 years :-)

That's exactly how Karl and I reason, but with a somewhat different
conclusion.

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> Óscar Fuentes writes:
>
>  > > On the other hand, how many VCS transitions have you managed for
>  > > Emacs-sized projects?  I've done two so far.  I can say from
>  > > experience the cost of support is not polynomial in extra workflows
>  > > during the transition.
>  > 
>  > Okay. Your experience trumps over my reasoning. Page deleted.
>
> I'm going to keep a copy (unless my browser has crashed in the
> meantime ;-) and integrate some of it into the section of our page on
> stacked branches.  Is that OK with you?

It seems contradictory to point out the cost of support associated to
having several workflows and then reintroduce one workflow when the
author deleted it for alleviating the problem.

Karl recovered the page and made some editions to it.

Please see my response to him and reconsider your above suggestion in
the light of the new state of the documentation.

[snip]

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Óscar Fuentes writes:

 > It seems contradictory to point out the cost of support associated to
 > having several workflows and then reintroduce one workflow when the
 > author deleted it for alleviating the problem.

It would be if (a) Karl and I were the same person and (b) the wiki
reported conflicts.

Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:
> Óscar Fuentes writes:
>  > It seems contradictory to point out the cost of support associated to
>  > having several workflows and then reintroduce one workflow when the
>  > author deleted it for alleviating the problem.
>
> It would be if (a) Karl and I were the same person and (b) the wiki
> reported conflicts.

Yes.  I had no awareness I was "recovering" the page -- I never knew
that it had been deleted! :-)  My editing session on that page started
before the deletion.

But I don't regret having revived it, now that it makes clear that we
recommend a more dVCS-ish way, and that BzrForEmacsDevs is a superset of
it.  As Glenn Morris and a couple of others have requested that it stay
around, I certainly won't delete it.

The main thing is to provide clear directions for those coming in with
no prior opinion.  People who already know they prefer the quick-start
guide are best served by getting one -- for me, the only question was
how to provide that to them *without* confusing anyone else, and I think
we've found a way to do that.

-Karl

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> Óscar Fuentes writes:
>
>  > It seems contradictory to point out the cost of support associated to
>  > having several workflows and then reintroduce one workflow when the
>  > author deleted it for alleviating the problem.
>
> It would be if (a) Karl and I were the same person and (b) the wiki
> reported conflicts.

Karl's action has nothing to do here. Wasn't it clear on the quoted
text? I was talking about you:

> "Stephen J. Turnbull" <stephen@xemacs.org> writes:
>  > Óscar Fuentes writes:
>  > > "Stephen J. Turnbull" <stephen@xemacs.org> writes:
>  > > On the other hand, how many VCS transitions have you managed for
>  > > Emacs-sized projects?  I've done two so far.  I can say from
>  > > experience the cost of support is not polynomial in extra workflows
>  > > during the transition.
>  > 
>  > Okay. Your experience trumps over my reasoning. Page deleted.
>
> I'm going to keep a copy (unless my browser has crashed in the
> meantime ;-) and integrate some of it into the section of our page on
> stacked branches.  Is that OK with you?

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Óscar Fuentes writes:

 > Karl's action has nothing to do here. Wasn't it clear on the quoted
 > text? I was talking about you:

Reread the thread.  Since you insisted on keeping your page, IIRC I've
said nothing since about deleting that page, and in fact have added
references to it from the main page on the assumption it was going to
stay.  It was Karl who asked you to delete it more recently.

True I supported his argument that having too many workflows can be
confusing against your claim that it won't be, but that doesn't mean
that I supported his request to delete the page.  Especially since RMS
clearly wants to keep it, and even make it the recommended workflow --
and if things go that way, there's no point in paying attention to me
'cause I'll be gone.

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> Óscar Fuentes writes:
>
>  > Karl's action has nothing to do here. Wasn't it clear on the quoted
>  > text? I was talking about you:
>
> Reread the thread.

The sequence of events that raised this subthread was:

Karl: It would be a good thing if you delete the page.

Oscar: I think that the page will reduce the amount of support that
emacs hackers will need on the transition.

Stephen: My experience says that having multiple workflows increases the
support load significantly.

Oscar: Okay, then I'll delete the page (so there is one less workflow to
care about)

Stephen: I'll like to put back that workflow on the available
documentation.

So you said that having multiple workflows increases the burden, then I
remove one workflow and you propose to add it back to the
documentation. That's what I find contradictory.

It is just that the pedantic maths freak in me can't resist pointing out
logical inconsistencies :-)

[snip]

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Óscar Fuentes writes:

 > Stephen: I'll like to put back that workflow on the available
 > documentation.

You're misrepresenting what I wrote.  Please don't do that.

Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:
> Óscar Fuentes writes:
>  > Karl's action has nothing to do here. Wasn't it clear on the quoted
>  > text? I was talking about you:
>
> Reread the thread.  Since you insisted on keeping your page, IIRC I've
> said nothing since about deleting that page, and in fact have added
> references to it from the main page on the assumption it was going to
> stay.  It was Karl who asked you to delete it more recently.
>
> True I supported his argument that having too many workflows can be
> confusing against your claim that it won't be, but that doesn't mean
> that I supported his request to delete the page.  Especially since RMS
> clearly wants to keep it, and even make it the recommended workflow --
> and if things go that way, there's no point in paying attention to me
> 'cause I'll be gone.

Heh.  I'll volunteer to have been inconsistent with something I
previously said, if it will stop this particular subthread :-).

Anyway, the thing that upsets people about too many choices is being
ill-equipped to deal with them.  So rather than delete workflow
documentation that some people (RMS, Glenn Morris, et al) find useful, I
think a strategy of being clear about

  - our recommended entry point (for those who need one), and
  - what each piece of documentation is for, and
  - how it relates to the others

is best.  That default entry point should be BzrForEmacsDevs, IMHO.

I think we're close to switching now; it depends on the pretest
schedule, which I'm not following.  I'll post separately about that.

-Karl

Re: Basic Bazaar guide for Emacs hackers.

[Richard Stallman]

    Okay. Your experience trumps over my reasoning. Page deleted.

What page did you delete?  I hope it was not your intro to simple use
of Bzr.  I saved a copy; if necessary I will republish it.

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

Richard Stallman <rms@gnu.org> writes:

>     Okay. Your experience trumps over my reasoning. Page deleted.
>
> What page did you delete?  I hope it was not your intro to simple use
> of Bzr.  I saved a copy; if necessary I will republish it.

The page was restored by Karl Fogel some minutes later with a note at
the beginning encouraging the reader to try the distributed workflow.

I'm not against recommending the distributed workflow. Actually, the
workflow that I use for my work is far more complex than the distributed
one recommended by Karl. What I find puzzling is the hostility towards
the centralized workflow described on BzrQuickStartForEmacsDevs. It is a
correct practice, which Bazaar proudly advertises as one of its multiple
supported workflows. In the context of Emacs, every developer can use
the distributed workflow, the centralized one or even switch between
them at any time without causing harm to the project or inconveniencing
other developers, as far as he follows some simple rules when he sends
his changes upstream.

I have the impression that some people thinks that having developers not
using a distributed workflow since day one would signal a failed
transition, or a failure of Bazaar itself adapting to the project. Quite
the contrary: the fact that Bazaar supports multiple compatible
workflows allowing each user to choose whatever suits him better is,
possibly, the best selling point for Bazaar.

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

On Tue, Dec 1, 2009 at 1:21 AM, Óscar Fuentes <ofv@wanadoo.es> wrote:
> I'm not against recommending the distributed workflow. Actually, the
> workflow that I use for my work is far more complex than the distributed
> one recommended by Karl. What I find puzzling is the hostility towards
> the centralized workflow described on BzrQuickStartForEmacsDevs. It is a
> correct practice, which Bazaar proudly advertises as one of its multiple
> supported workflows. In the context of Emacs, every developer can use
> the distributed workflow, the centralized one or even switch between
> them at any time without causing harm to the project or inconveniencing
> other developers, as far as he follows some simple rules when he sends
> his changes upstream.
>
> I have the impression that some people thinks that having developers not
> using a distributed workflow since day one would signal a failed
> transition, or a failure of Bazaar itself adapting to the project. Quite
> the contrary: the fact that Bazaar supports multiple compatible
> workflows allowing each user to choose whatever suits him better is,
> possibly, the best selling point for Bazaar.

Sorry, if I ever gave that impression, I didn't mean to.

I don't think there's anything objectively wrong with someone
choosing the non-distributed workflow.  My concern is simply that
the Emacs project be able to clearly and unambiguously answer
the question "How do I hack on Emacs?"

The answer to that question *cannot* be "First go learn all the
different ways you can use Bazaar, then pick one, set yourself
up, and start coding."  That would be a hackability nightmare
for contributors, and a support nightmare for the project.

The multiplicity of workflows available in Bazaar has not, historically,
been a selling point, much as we might theorize it is.  Instead, the
richness of the tool tends to confuse users -- even sophisticated
users, sometimes.  (The Bazaar project realizes this and is working
to fix it.)

Stephen and I have worked on distributed projects using Bazaar
before, and both find that the workflow described in BzrForEmacsDevs
strikes a decent balance between ease of learning and suitability for
the Emacs project.  Therefore, we want to hand it out as the *default*
answer for the question "How do I hack on Emacs?"

That doesn't mean it's the only way.  But I can tell you right now (having
experienced *exactly this phenomenon* in other projects) that if every
time someone posts asking how to get involved now that Emacs is
in Bazaar, they get several different and seemingly inconsistent answers,
their hacking energy will be quickly depleted.

We've been there.  We've seen it.  I'll consider it both a personal and a
systemic failure if this project fails to take advantage of this highly
relevant experience accumulated by (at least) two of its participants :-).

Re: Basic Bazaar guide for Emacs hackers.

[Jason Rumney]

Karl Fogel wrote:
> I don't think there's anything objectively wrong with someone
> choosing the non-distributed workflow.  My concern is simply that
> the Emacs project be able to clearly and unambiguously answer
> the question "How do I hack on Emacs?"
>   

While the distributed workflow might be a better approach for people 
starting with a clean slate, existing developers (and users who track 
CVS) do not necessarily have the time to invest in learning a new 
workflow immediately, and are looking for minimum disruption immediately 
after the switch from CVS to bzr. So there is definite value in an 
additional document describing a quick and painless transition from CVS, 
and probably a migration path to the distributed workflow for when the 
developer has time to adjust their habits.

Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

On Tue, Dec 1, 2009 at 3:34 AM, Jason Rumney <jasonr@gnu.org> wrote:
> Karl Fogel wrote:
>>
>> I don't think there's anything objectively wrong with someone
>> choosing the non-distributed workflow.  My concern is simply that
>> the Emacs project be able to clearly and unambiguously answer
>> the question "How do I hack on Emacs?"
>
> While the distributed workflow might be a better approach for people
> starting with a clean slate, existing developers (and users who track CVS)
> do not necessarily have the time to invest in learning a new workflow
> immediately, and are looking for minimum disruption immediately after the
> switch from CVS to bzr. So there is definite value in an additional document
> describing a quick and painless transition from CVS, and probably a
> migration path to the distributed workflow for when the developer has time
> to adjust their habits.

Absolutely.  We already have the additional document, and it is
prominently linked to, so no problems there.  I myself don't know
how to document the migration path from there to the distributed
workflow, but I hope that someone who does will do so.

-Karl

Re: Basic Bazaar guide for Emacs hackers.

[Eli Zaretskii]

> Date: Tue, 1 Dec 2009 10:26:02 -0500
> From: Karl Fogel <kfogel@red-bean.com>
> Cc: =?ISO-8859-1?Q?=D3scar_Fuentes?= <ofv@wanadoo.es>, rms@gnu.org,
> 	emacs-devel@gnu.org
> 
> > While the distributed workflow might be a better approach for people
> > starting with a clean slate, existing developers (and users who track CVS)
> > do not necessarily have the time to invest in learning a new workflow
> > immediately, and are looking for minimum disruption immediately after the
> > switch from CVS to bzr. So there is definite value in an additional document
> > describing a quick and painless transition from CVS, and probably a
> > migration path to the distributed workflow for when the developer has time
> > to adjust their habits.
> 
> Absolutely.  We already have the additional document, and it is
> prominently linked to, so no problems there.

So, as long as we all think that the "Quick Start" page will be useful
to some, here are a comment about it:

The setup and workflow described by this page is advertised (by its
parent "Bzr For Emacs Devs") as ``CVS-like''.  But this isn't really
accurate, is it?  The command shown to checkout the trunk is this:

    bzr checkout URL_TO_UPSTREAM_TRUNK trunk

However, IIUC, the slightly modified checkout command

    bzr checkout --lightweight URL_TO_UPSTREAM_TRUNK trunk

is a closer equivalent of the CVS checkout, because it only checks out
the working tree without creating a full local copy of history.  The
history is only needed if one wants to commit locally.  People who
don't plan on using local commits don't need to pay the extra price of
larger disk storage and probably also some additional time it takes to
do a heavyweight checkout.

OTOH, if we think that a heavyweight checkout is the recommended way,
then we should at least mention its main benefit -- the local commit.
Currently, the page only hints on that, but stops short of showing the
commands to use this potential:

  You have in your disk a copy of the VC history of the trunk branch
  since the last bzr update. Hence, Bazaar does not need to contact a
  server upstream for displaying logs, reverting edited files,
  annotating, etc. This is useful for working off-line.

  Bazaar makes possible to commit changes off-line to your local history
  and send them upstream in one batch.

Personally, I would do both: tell about --lightweight as the
equivalent of CVS, and also tell about the local commits available
with the heavyweight checkouts.  But that's me.

Re: Basic Bazaar guide for Emacs hackers.

[Jason Earl]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Tue, 1 Dec 2009 10:26:02 -0500
>> From: Karl Fogel <kfogel@red-bean.com>
>> Cc: =?ISO-8859-1?Q?=D3scar_Fuentes?= <ofv@wanadoo.es>, rms@gnu.org,
>> 	emacs-devel@gnu.org
>> 
>> > While the distributed workflow might be a better approach for
>> > people starting with a clean slate, existing developers (and users
>> > who track CVS) do not necessarily have the time to invest in
>> > learning a new workflow immediately, and are looking for minimum
>> > disruption immediately after the switch from CVS to bzr. So there
>> > is definite value in an additional document describing a quick and
>> > painless transition from CVS, and probably a migration path to the
>> > distributed workflow for when the developer has time to adjust
>> > their habits.
>> 
>> Absolutely.  We already have the additional document, and it is
>> prominently linked to, so no problems there.
>
> So, as long as we all think that the "Quick Start" page will be useful
> to some, here are a comment about it:
>
> The setup and workflow described by this page is advertised (by its
> parent "Bzr For Emacs Devs") as ``CVS-like''.  But this isn't really
> accurate, is it?  The command shown to checkout the trunk is this:
>
>     bzr checkout URL_TO_UPSTREAM_TRUNK trunk
>
> However, IIUC, the slightly modified checkout command
>
>     bzr checkout --lightweight URL_TO_UPSTREAM_TRUNK trunk

I *really* don't think that you want to advertise lightweight checkouts
that point to non-local URLs.

> is a closer equivalent of the CVS checkout, because it only checks out
> the working tree without creating a full local copy of history.  The
> history is only needed if one wants to commit locally.  People who
> don't plan on using local commits don't need to pay the extra price of
> larger disk storage and probably also some additional time it takes to
> do a heavyweight checkout.

The history is also needed if you want to do any sort of bzr command,
like bzr log or bzr annotate.  Heck, even bzr status requires access to
the parent branch.  Even if you don't want to commit locally (and with a
checkout you probably *don't* want to commit locally), it is still
worthwhile to have the branch history on a local disk.

Using a lightweight checkout might be a net win for people who are
simply interested in following Emacs development if the lightweight
checkout required less time to checkout or if it required you to
download less information, but that's simply not the case with the plain
jane http transport (I do not know if the smart server is an improvement
either, not that it matters as it appears that Savannah is not going to
provide one).

bzr checkouts *work* like cvs checkouts, you don't even need a fancy bzr
repository.  The primary difference is that they still work when
disconnected from the network.  Well, that and with bzr you can rename
files, and commits are atomic, and bzr is actively maintained, etc.

> OTOH, if we think that a heavyweight checkout is the recommended way,
> then we should at least mention its main benefit -- the local commit.
> Currently, the page only hints on that, but stops short of showing the
> commands to use this potential:
>
>   You have in your disk a copy of the VC history of the trunk branch
>   since the last bzr update. Hence, Bazaar does not need to contact a
>   server upstream for displaying logs, reverting edited files,
>   annotating, etc. This is useful for working off-line.
>
>   Bazaar makes possible to commit changes off-line to your local
>   history and send them upstream in one batch.
>
> Personally, I would do both: tell about --lightweight as the
> equivalent of CVS, and also tell about the local commits available
> with the heavyweight checkouts.  But that's me.

At some point we need to point people at the existing Bazaar
documentation.  I personally don't have a problem with CVS-style usage
of Bazaar.  In fact, one of the reasons that I like bzr is that it
allows for this type of usage in situations where it makes sense.

However, a lightweight checkout of a non-local branch is a real loser
performance wise, and it throws away many of the advantages that bzr has
over CVS.  The entire history of the mainline of Emacs can be compressed
into just under 200M.  The entire history of all of the branches of
Emacs is about 10% more than that.

I just don't think that lightweight checkouts is something that we want
to advertise.

Jason

Re: Basic Bazaar guide for Emacs hackers.

[Eli Zaretskii]

> From: Jason Earl <jearl@notengoamigos.org>
> Cc: Karl Fogel <kfogel@red-bean.com>,  ofv@wanadoo.es,  emacs-devel@gnu.org
> Date: Tue, 01 Dec 2009 12:56:26 -0700
> 
> The history is also needed if you want to do any sort of bzr command,
> like bzr log or bzr annotate.

As you well know, these go upstream in CVS as well.  So this is not
really a loss for people who want a familiar CVS-like setup.

> At some point we need to point people at the existing Bazaar
> documentation.

After reading through all of it, I think it's not organized well for a
single reading.  I needed to read both manuals several times before it
started making sense.  Showing one option (--lightweight) and one
command (commit --local) is hardly worth sending people to wade
through the canonical docs, just to find that it, too, says that a
lightweight checkout is almost like CVS.

Anyway, that's my last post on this issue.  I hope my opinions on this
are clear enough.  I don't think I will use the CVS-like setup, but I
see no reason not to help those who will.

Re: Basic Bazaar guide for Emacs hackers.

[Stefan Monnier]

>> The history is also needed if you want to do any sort of bzr command,
>> like bzr log or bzr annotate.
> As you well know, these go upstream in CVS as well.  So this is not
> really a loss for people who want a familiar CVS-like setup.

The performance will usually be significantly worse than with CVS.
E.g. if you do a "bzr log", it's likely that a lightweight checkout
accessing a remote repository over sftp will end up transfering the
entire history (e.g. 200MB for Emacs) over the network.
If you can access the repository over bzr+ssh, it might be a lot better
(a lot closer to cvs), but it's still likely to be slower than cvs, if
for nothing else that it's a discouraged usage.


        Stefan

Re: Basic Bazaar guide for Emacs hackers.

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Jason Earl <jearl@notengoamigos.org>,  kfogel@red-bean.com,  ofv@wanadoo.es,  emacs-devel@gnu.org
> Date: Tue, 01 Dec 2009 20:28:22 -0500
> 
> >> The history is also needed if you want to do any sort of bzr command,
> >> like bzr log or bzr annotate.
> > As you well know, these go upstream in CVS as well.  So this is not
> > really a loss for people who want a familiar CVS-like setup.
> 
> The performance will usually be significantly worse than with CVS.

Yes, it's slow.  "bzr annotate" in a lightweight checkout takes almost
3 minutes here.  What's worse, it seems to send the entire annotated
source downstream in one big chunk, whereas CVS seemed to send it in
smaller chunks, so if you pipe the output to a pager, as you normally
would, with CVS you could begin reading before the whole file was
received.  (With a local branch, "bzr annotate" takes about 30
seconds, not exactly the speed of light, either.)  "bzr log" takes
about a minute for a lightweight checkout vs 10 seconds for a local
branch.

So I guess if you use annotate and log a lot, then lightweight
checkouts are not for you.

Re: Basic Bazaar guide for Emacs hackers.

[Stefan Monnier]

> Yes, it's slow.  "bzr annotate" in a lightweight checkout takes almost
> 3 minutes here.  What's worse, it seems to send the entire annotated
> source downstream in one big chunk, whereas CVS seemed to send it in

Remember that the network protocol used is sftp, so the remote
repository is "dumb" and cannot perform any operation such as
"annotate".  So when you do an "annotate", nothing is sent upstream
other than commands to fetch files that contain the relevant parts of
history, and then the annotate operation is performed locally.

> received.  (With a local branch, "bzr annotate" takes about 30
> seconds, not exactly the speed of light, either.)

Yes, it's a fairly slow operation, sadly.  I encourage you to complain
to the Bazaar developers about it,


        Stefan

Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> Yes, it's slow.  "bzr annotate" in a lightweight checkout takes almost
>> 3 minutes here.  What's worse, it seems to send the entire annotated
>> source downstream in one big chunk, whereas CVS seemed to send it in
>
> Remember that the network protocol used is sftp, so the remote
> repository is "dumb" and cannot perform any operation such as
> "annotate".  So when you do an "annotate", nothing is sent upstream
> other than commands to fetch files that contain the relevant parts of
> history, and then the annotate operation is performed locally.

I'm hoping we can change that soon, with bzr+ssh access.  See
https://savannah.gnu.org/support/?107077 for details.

In related matters, I'm hoping we can get Bazaar 2.0.2 on Savannah.
https://lists.ubuntu.com/archives/bazaar/2009q4/064932.html quotes
Norbert Tretkowski as saying he has uploaded a bzr 2.0.2 lenny backport
to http://people.debian.org/~nobse/temp/bzr/, and that he'll upload it
to backports.org soon.  http://packages.debian.org/lenny-backports/bzr
doesn't have it yet, but I'm asking another uploader in IRC about it
right now (Jelmer Vernooij).  Transcript below.

-Karl

<kfogel> jelmer: have you seen
         https://lists.ubuntu.com/archives/bazaar/2009q4/064932.html?
         Apparently Norbert Tretkowski has uploaded a bzr 2.0.2 lenny
         backport to http://people.debian.org/~nobse/temp/bzr/.  He said
         he was going to upload it to backports.org, but I don't see it
         at http://packages.debian.org/lenny-backports/bzr.  Is this
         something you can do?  (It would help us for the Emacs
         switchover.)

<jelmer> kfogel: I am able to upload, but we should probably check with
         him

<kfogel> jelmer: I don't know him, and his email address doesn't appear
         to be in that mail, but do you know how to contact him?  I can
         try to track him down if not.

<jelmer> kfogel, his email address is nobse at debian.org

<jelmer> he is also here on IRC as nobse

<jelmer> If you haven't asked him about the backports yet, I'm happy to
         talk to him

<kfogel> jelmer: I haven't talked to him about it yet.  If you can
         coordinate with him, that'd be great.  As soon as it's on
         backports, we'll ask the savannah.gnu.org admins to install it
         [...]

Re: Basic Bazaar guide for Emacs hackers.

[Eli Zaretskii]

> From: Karl Fogel <kfogel@red-bean.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  jearl@notengoamigos.org,  ofv@wanadoo.es,  emacs-devel@gnu.org
> Date: Wed, 02 Dec 2009 10:59:01 -0500
> 
> In related matters, I'm hoping we can get Bazaar 2.0.2 on Savannah.

What about fencepost?  I wrote to sysadmins asking for that (they have
v1.2.0!) a week ago, but there was no response, and the version is
still 1.2.0.

Richard, can you perhaps speed it up?  I dod almost all of my bidi
development on fencepost, so that's where I need bzr first and
foremost when we switch.

Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

Eli Zaretskii <eliz@gnu.org> writes:
>> In related matters, I'm hoping we can get Bazaar 2.0.2 on Savannah.
>
> What about fencepost?  I wrote to sysadmins asking for that (they have
> v1.2.0!) a week ago, but there was no response, and the version is
> still 1.2.0.
>
> Richard, can you perhaps speed it up?  I dod almost all of my bidi
> development on fencepost, so that's where I need bzr first and
> foremost when we switch.

For those of us who aren't normally affected by these things:

What is the difference between fencepost and savannah?  Are there any
other hosts we should be thinking about?

(The usual Internet searches do not provide a clear answer.)

Thanks,
-Karl

Re: Basic Bazaar guide for Emacs hackers.

[Eli Zaretskii]

> From: Karl Fogel <kfogel@red-bean.com>
> Cc: Richard Stallman <rms@gnu.org>,  monnier@iro.umontreal.ca,  jearl@notengoamigos.org,  emacs-devel@gnu.org
> Date: Wed, 02 Dec 2009 13:16:41 -0500
> 
> What is the difference between fencepost and savannah?

All I know is that fencepost.gnu.org is the GNU Project shell server,
i.e. that's where you get a shell account from the GNU Project.

Re: Basic Bazaar guide for Emacs hackers.

[Richard Stallman]

I will ping the sysadmins about updating bzr on fencepost.

Re: Basic Bazaar guide for Emacs hackers.

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: eliz@gnu.org, monnier@iro.umontreal.ca, jearl@notengoamigos.org,
> 	emacs-devel@gnu.org
> Reply-to: rms@gnu.org
> Date: Thu, 03 Dec 2009 07:22:19 -0500
> 
> I will ping the sysadmins about updating bzr on fencepost.

Thank you.

Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

Richard Stallman <rms@gnu.org> writes:
> I will ping the sysadmins about updating bzr on fencepost.

Thank you!

Please have them upgrade to bzr 2.0.2, which is in Debian backports now.
The Bazaar developers say it is noticeably better to run 2.0.2 than 1.x
versions (which is what we have now).  Search for "bzr_2.0.2" in here:

  http://www.backports.org/debian/pool/main/b/bzr/

Assuming they upgrade on both fencepost and savannah, this might solve
our loggerhead (repository/branch browsing) problems too (sr #107142).
I asked in #bzr and the loggerhead 1.17 should be compatible with Bazaar
2.0.2.

-Karl

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

Karl Fogel <kfogel@red-bean.com> writes:

> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>>> Yes, it's slow.  "bzr annotate" in a lightweight checkout takes almost
>>> 3 minutes here.  What's worse, it seems to send the entire annotated
>>> source downstream in one big chunk, whereas CVS seemed to send it in
>>
>> Remember that the network protocol used is sftp, so the remote
>> repository is "dumb" and cannot perform any operation such as
>> "annotate".  So when you do an "annotate", nothing is sent upstream
>> other than commands to fetch files that contain the relevant parts of
>> history, and then the annotate operation is performed locally.
>
> I'm hoping we can change that soon, with bzr+ssh access.  See
> https://savannah.gnu.org/support/?107077 for details.

Certainly, we don't want to to use the savannah server for `annotate'
nor for other VC operations that can be performed locally.

If some people start using lightweight checkouts, a few simultaneous
`log' and `annotate' can bring the server's CPU to its knees. I'll vote
for disabling those operations on the server, if possible.

BTW, how well does concurrency the smart server? It blocks writes when a
read operation is performed?

[snip]

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Martin Albisetti]

On Wed, Dec 2, 2009 at 3:40 PM, Óscar Fuentes <ofv@wanadoo.es> wrote:
> BTW, how well does concurrency the smart server? It blocks writes when a
> read operation is performed?

Pretty well. Launchpad uses the smart server extensively.
Reads do not generally block writes, AFAICT.


-- 
Martin

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Óscar Fuentes writes:

 > BTW, how well does concurrency the smart server? It blocks writes when a
 > read operation is performed?

Well, and no.  There have been bugs in locking, of course, but the
basic design has always been sound and the implementation has only
rarely been excessively fussy about locking.  In fact as far as I know
most of the write operation (ie, repacking) is done without locking
the repo; the history data is written to temp files, and locks are
held just long enough to update the metadata atomically.

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

[snip]

>> received.  (With a local branch, "bzr annotate" takes about 30
>> seconds, not exactly the speed of light, either.)
>
> Yes, it's a fairly slow operation, sadly.  I encourage you to complain
> to the Bazaar developers about it,

Operations that traverse history are intrinsically slow in Bazaar. Some
improvements can be made (microoptimizations, mostly) but they will
never be as fast as CVS (and I'm talking about bzr with local history vs
remote CVS server).

OTOH, `log' and `annotate' with local history are CPU-bound. A `log' in
almost any Emacs source file takes 6.2 seconds on a 2.4 GHz
workstation-class CPU and 22 seconds on a netbook. Worse, the `log' does
not produce any output until the end, and it requires the same time even
when you use the -l command line option for limiting the output at the
first N revisions. After I complained about this on Bazaar's ml, a
developer is attempting to change `log' for outputting stuff as soon as
possible and stop when the required number of revisions is met, but so
far he is disappointed seeing that his change makes the total time
required by a plain `bzr log' even larger. Of course this is a wrong
POV, but they give a lot of importance to raw performance numbers.

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Eli Zaretskii writes:

 > I hope my opinions on this are clear enough.  I don't think I will
 > use the CVS-like setup, but I see no reason not to help those who
 > will.

So you're going to support those users?  Great!

Re: Basic Bazaar guide for Emacs hackers.

[Richard Stallman]

To write information on a certain way of using bzr does not imply that
you have an obligation to answer users' questions about it.

Re: Basic Bazaar guide for Emacs hackers.

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

> To write information on a certain way of using bzr does not imply that
> you have an obligation to answer users' questions about it.

It has been my experience that it wastes far too much time and emotional
effort to omit answers for reoccuring questions one actually considers
somebody else's business.

Nobody thanks you for educating him, in particularly not when you do
that in the almost compulsory terse tone when asked the same unnecessary
question for the hundredth time.

-- 
David Kastrup

Re: Basic Bazaar guide for Emacs hackers.

[Stephen J. Turnbull]

Richard Stallman writes:

 > To write information on a certain way of using bzr does not imply that
 > you have an obligation to answer users' questions about it.

Of course it does not.  In fact, I no longer feel any (self-imposed)
obligation to answer any questions about Bazaar. :-)

That won't stop me if I happen to have time or interest, of course,
but I've to this point "made" about a full work day's worth of time to
do productive work on the thread (ie, editing the wiki and/or
researching Bazaar behavior, not including writing email) sooner than
I would if just for my own interest.  No more -- thanks for saving me
the time and effort! :-)

Re: Basic Bazaar guide for Emacs hackers.

[Richard Stallman]

    > The setup and workflow described by this page is advertised (by its
    > parent "Bzr For Emacs Devs") as ``CVS-like''.  But this isn't really
    > accurate, is it?  The command shown to checkout the trunk is this:

If several methods are simple and fairly similar to CVS, the Quick
Start recommendation does not have to be the one that is absolutely
simplest or absolutely most similar to CVS.  If another that is also
rather simple and rather like CVS is better in some other way,
it is ok to use.

So there is no a priori reason to change it to suggest lightweight
checkins.

Re: Basic Bazaar guide for Emacs hackers.

[Óscar Fuentes]

Eli Zaretskii <eliz@gnu.org> writes:

> The setup and workflow described by this page is advertised (by its
> parent "Bzr For Emacs Devs") as ``CVS-like''.

I'll better describe that workflow as "centralized", versus the
"distributed" one described on BzrForEmacsDevs.

> But this isn't really accurate, is it?  The command shown to checkout
> the trunk is this:
>
>     bzr checkout URL_TO_UPSTREAM_TRUNK trunk
>
> However, IIUC, the slightly modified checkout command
>
>     bzr checkout --lightweight URL_TO_UPSTREAM_TRUNK trunk
>
> is a closer equivalent of the CVS checkout, because it only checks out
> the working tree without creating a full local copy of history.

Please note that the guide itself does not pretend to simulate CVS, but
just exploit the concepts familiar to any CVS user for easing his
transition to Bazaar as the Emacs' VCS.

> The history is only needed if one wants to commit locally.  People who
> don't plan on using local commits don't need to pay the extra price of
> larger disk storage and probably also some additional time it takes to
> do a heavyweight checkout.

The guide's goal is not the be exhaustive, but be simple. Mentioning the
--lightweight option would increase complexity explaining one variant
that hardly any Emacs hacker would appreciate once he starts using that
setup. I can expand on this if you are interested.

> OTOH, if we think that a heavyweight checkout is the recommended way,
> then we should at least mention its main benefit -- the local commit.
> Currently, the page only hints on that, but stops short of showing the
> commands to use this potential:

On a previous version of the wiki page there was a brief description of
--local option for `commit'. It was removed following the suggestions of
one the authors of the other guide.

[snip]

> Personally, I would do both: tell about --lightweight as the
> equivalent of CVS, and also tell about the local commits available
> with the heavyweight checkouts.  But that's me.

Thanks for your comments.

-- 
Óscar

Re: Basic Bazaar guide for Emacs hackers.

[Karl Fogel]

Óscar Fuentes <ofv@wanadoo.es> writes:
> Eli Zaretskii <eliz@gnu.org> writes:
>> The setup and workflow described by this page is advertised (by its
>> parent "Bzr For Emacs Devs") as ``CVS-like''.
>
> I'll better describe that workflow as "centralized", versus the
> "distributed" one described on BzrForEmacsDevs.

Agreed, FWIW (I think I introduced "CVS-like" there, but I'm not wedded
to it, and "centralized" may be the better term).

-Karl

Re: Basic Bazaar guide for Emacs hackers.

[Stefan Monnier]

> is a closer equivalent of the CVS checkout, because it only checks out
> the working tree without creating a full local copy of history.  The
> history is only needed if one wants to commit locally.  People who
> don't plan on using local commits don't need to pay the extra price of
> larger disk storage and probably also some additional time it takes to
> do a heavyweight checkout.

> OTOH, if we think that a heavyweight checkout is the recommended way,
> then we should at least mention its main benefit -- the local commit.

The local commit (at least via --local) is not for the faint of heart
(at least it got me confused several times, because when you later dp
an "update", it seems to label the conflicts in ways that make me
believe that my changes are actually the ones fetched from upstream and
vice-versa).
So, no, it's not the main feature.  The main feature is that "bzr diff",
"bzr log", and friends will work without requiring access to the
remote repository.

> Currently, the page only hints on that, but stops short of showing the
> commands to use this potential:

>   You have in your disk a copy of the VC history of the trunk branch
>   since the last bzr update. Hence, Bazaar does not need to contact a
>   server upstream for displaying logs, reverting edited files,
>   annotating, etc. This is useful for working off-line.

>   Bazaar makes possible to commit changes off-line to your local history
>   and send them upstream in one batch.

> Personally, I would do both: tell about --lightweight as the
> equivalent of CVS, and also tell about the local commits available
> with the heavyweight checkouts.  But that's me.

I could agree to adding some comment about the use of "unbind" to turn
a heavyweight checkout into a plain branch.  But maybe it's even better
to not present "heavyweight checkout" and instead only present the
"standalone branch" instead:

checkout via:    bzr branch <foo>
update via:      bzr pull
commit via:      bzr commit; bzr push


        Stefan

Re: Basic Bazaar guide for Emacs hackers.

[Richard Stallman]

    I have the impression that some people thinks that having developers not
    using a distributed workflow since day one would signal a failed
    transition, or a failure of Bazaar itself adapting to the project. Quite
    the contrary: the fact that Bazaar supports multiple compatible
    workflows allowing each user to choose whatever suits him better is,
    possibly, the best selling point for Bazaar.

I agree.  If the decentralized method helps you, by all means use it.
I am even prepared to believe that using it is a worthwhile investment
for most or all people making medium or large changes.  I only object
to pushing it on people making small changes, the sort that with CVS would
be installed all at once.

Re: Basic Bazaar guide for Emacs hackers.

[Glenn Morris]

Óscar Fuentes wrote:

> http://www.emacswiki.org/cgi-bin/emacs/BzrQuickStartForEmacsDevs

Thanks for writing such a document. A basic "here is what you need to
do in order to keep on doing what you have been doing" is all I have
wanted to see. Please don't delete it.