[Fwd: Propozed bzr merge manpage and errmsg modifications]

[Robert Collins]

On Wed, 2007-05-23 at 22:33 +0200, John Arbash Meinel wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> I'm forwarding this message from Mike (sorry my keyboard doesn't like to
> type your name correctly)
> 
> We were chatting on IRC, and he had a few comments about how some of the
> documentation and user errors could be tweaked to be a little bit more
> understandable.
> 
> I'm forwarding it first, and then I'll try to respond to it on the list.

I think the response got dropped ...

> > -------- Forwarded Message --------
> > From: Michał Andrzej Woźniak <mike at rysiek.ath.cx>
> > To: john at arbash-meinel.com
> > Subject: Propozed bzr merge manpage and errmsg modifications
> > Date: Wed, 23 May 2007 14:38:45 +0200
> > 
> > Hi, rysiek|pl here,
> > 
> > the error message displayed upon trying to merge after the previous
> > merge was 
> > not committed is as follows:
> > 
> > "bzr: ERROR: Working tree has uncommitted changes."
> > 
> > Me and my friend found it definitely not informative enough (it
> > didn't get to 
> > us that we need to do a bzr commit afterwards), so here's the
> > proposed 
> > modification:
> >
> > "bzr: ERROR: Working tree has uncommitted changes. Did you remember
> > to do bzr 
> > commit after bzr merge in the branch?"

There can be many reasons for having uncommitted changes; I dont think
its appropriate to list just one, and particularly not one that is
internalised so quickly. However I do think that the message can be
usefully expanded, perhaps by suggesting 'use bzr status to see what has
not been committed'. This will in the case of a merge list pending
merges and thus should be discoverable.

> > and in the manpage, the last paragraph of bzr merge:
> > 
> > "The results of the merge are placed into the destination working
> > directory, 
> > where they can be reviewed (with bzr diff), tested, and then
> > committed to 
> > record the result of the merge."
> > 
> > I would propose to change to:
> > 
> > "The results of the merge are placed into the destination working
> > directory, 
> > where they can be reviewed (with bzr diff) and tested. Afterwards,
> > they need 
> > to be committed to record the result of the merge."

+1 on this change, its clearer than the run-on sentence.

> > Maybe a FAQ entry for the error message would also be a good idea?
> > 
> > Q: 'bzr: ERROR: Working tree has uncommitted changes.' What the?..
> > A: Bazaar handles branch merges a bit differently to what one might
> > be used to 
> > from other RCS. A merge needs to be committed for the changes to
> > take effect. 
> > So, after a bzr merge, when you are happy with changes that are
> > going to take 
> > place (you can browse through them e.g. with bzr diff), remember to
> > do a bzr 
> > commit.

I think its a misfeature if we need a FAQ entry to explain an error - we
should be able to solve this in the error itself, possible with a help
topic on 'merge' ?

> > I am a bazaar newbie so I might have gotten things and nomenclature
> > a wee bit 
> > wrong. Please feel free to make any changes you would find
> > desirable, of 
> > course.
> > 
> > Cheers and thanks for clearing this up
> > Mike

Cheers,
Rob
-- 
GPG key available at: <http://www.robertcollins.net/keys.txt>.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20070530/12471287/attachment.pgp