[MERGE] Explain --message and --mail-to in the help of merge-directive

[Martin Pool]

On 6/29/07, Aaron Bentley <aaron.bentley at utoronto.ca> wrote:
> James Westby wrote:
> > On (28/06/07 16:18), Aaron Bentley wrote:
>
> >> This seems to basically repeat the option help.  And since no one should
> >> be using these options, I hesitate to give them prominence.
> >
> > If no-one should be using them then that is fine. However I am not sure
> > why you say that. I use these options for the bundles I just sent in.

> Yes, and as I noted, you are making extra work for me by doing that.  I
> would appreciate it if you would stop it.

I'm sure James was just trying to use the tool in what seemed to him
the right way, given the documentation that's there now.

I wasn't sure what was wrong with using them, but Aaron says that the
problem is that Bundle Buggy doesn't understand inline patches, which
is what this sends.  We should probably fix it to send attachments?

>
> > Could you explain the intended use of this command please?
>
> $ bzr merge-directive > ~/patches/my-patch-name
>
> Now create a message in your mail client and attach the merge-directive
> to it.
>
> Some patches are so trivial that they don't need any explanation, but
> most of them deserve an explanation beyond what goes in the subject line.

Right, but I would expect the merge directive would capture that as
the message.  I suppose you might sometimes want incidental comments
that would go into the mail but not the committed revision.

As someone else  commented yesterday, needing to save the file then
attach it from your mail client is quite a few more steps.  If you
just want to send the thing and be done then getting the description
and sending mail all in one go is highly desirable.

As far as the actual substance of the patch: James's descriptions do
seem a bit redundant with the option messages.  James, did you think
the description there was not sufficiently prominent?   Or maybe by
way of general description we should add "The merge directive is sent
to stdout unless --mail-to is given...", maybe also give the typical
usage, and add a note that the mail is sent inline not as mime
(https://bugs.launchpad.net/bzr/+bug/123922).

-- 
Martin