Re: [PATCH 1 of 1] docs/overview.txt: Provide short mercurial HOWTO

[wino <wino at piments dot com>]

Hi Titus,

nice guide. I've been putting off learning how to use hg , this intro is 
very useful.

Thanks.

On 05/21/10 18:27, Yann E. MORIN wrote:
> Titus, All,
>
> On Friday 21 May 2010 15:56:42 Titus von Boxberg wrote:
> > # HG changeset patch
> > # User Titus von Boxberg<titus@v9g.de>
> > # Date 1274449425 -7200
> > # Node ID 15c9bd7328f0310785ee8e3c581971ef173178b1
> > # Parent  0a59fff8643bc15036135d081deb087cef53fde2
> > docs/overview.txt: Provide short mercurial HOWTO
>
> Nice HOWTO! :-)
>
> [--SNIP--]
> > +CONTRIBUTING YOUR PATCHES:
> > +
> > +The command hg email sends your patches as emails.
> > +The flag --outgoing selects all patches that are not yet
> > +put into the upstream repository.
> > +These emails get the subject
> > +[PATCH x of<your patch queue length>]<your short patch #x description>.
>
> Add something like:
>     The mails are correctly threaded below the introductory message.
>
> > +In addition, it lets you prepare a first introductory email where you can
> > +extend the default subject [PATCH 0 of<your patch queue length>]
> > +and prepare a message body where you should describe the scope of
> > +and motivation for the patches.
> > +Note: replace " (at) " with "@"
>
> This paragraph is a bit hard to read. Maybe something like:
>
> ---8<---
> CONTRIBUTING YOUR PATCHES:
>
>    Once you are comptempt with your patch series, you can (you should!)
>    contribute them back to upstream.
>
>    This is handily done using the 'hg email' command.

c/handily/easily/

>    'hg email' sends changesets to a specified list of recipients, each patch
>    in its own email. Each email get the subject set to:
>      [PATCH x of n]<summary line>
>
>    where 'x' is the patch index in the series (plus 1), and 'n' is the number
>    of patches is the series. The body of the email is the complete patch, plus
>    a handful of metadata, that helps properly apply the patch, keeping the log
>    message, attribution and date, tracking file changes (move, delete, modes...)
>
>    'hg email' also threads all outgoing patch emails below an introductory
>    message. You should use the introductory message to describe the scope
>    and motivation for the complete patch series. You can also extend the
>    subject line with a summary introduction:
>      [PATCH 0 of n]<summary line for whole series>
>
>    Here is a sample 'hg email' complete command line:
> ---8<---
>
> > +  hg email --outgoing --intro   \
> > +           --from '"Your Full NAME"<your.email (at) your.domain>'   \
>
> In fact, the --from is not needed, as it defaults to what is in ~/.hgrc in
> the "[ui]::username" field, or the "[email]::from" field.
>
> I originally included it in the example command line because I did not
> include the ~/.hgrc bits. With your explanations, it is no longer needed.
>
> > +           --to '"Yann E. MORIN"<yann.morin.1998 (at) anciens.enib.fr>'  \
> > +           --cc 'crossgcc (at) sourceware.org'
> > +
> > +Use hg email with the additional command line switch -n to
> > +first have a look at the emails without actually sending them.
>
> [--SNIP--]
>
> > +RESENDING YOUR REEDITED PATCH:
> > +
> > +Now you may want to contribute your edited patch short_patch_name2.
> > +The command hg email lets you send a particular patch with the
> > +command line argument -r<revision>.
> > +BEWARE: This<revision>  is NOT the patch number in your queue,
> > +it is the changeset number of your repository.
> > +  # Thus, you have to find out the repository revision first:
> > +  hg log | more
> > +  # shows something like
> > +    ...
> > +    changeset:<revision>:<id>
> > +    tag:          short_patch_name2
> > +    ...
> > +
> > +The<revision>  after "changeset:" is the one hg email expects for the -r command line argument.
> > +  # So, the following command resends that revision:
> > +  hg email -r<revision>  \
> > +     --to '"Yann E. MORIN"<yann.morin.1998 (at) anciens.enib.fr>' \
> > +     --cc 'crossgcc (at) sourceware.org'
> > +  # again, you can use -n first to make sure everything is ok with that email.
>
> When a patch series is modified, it is tradition to repost the whole
> series, rather than only the changed items in the series.
>
> As a reviewer point of view, it is much simpler when the series is complete.
> Having only the changed bits imposes to go back into the mail history to get
> the missing parts. If the round-trip from the old submission to the new  one
> is long enough, finding again the old series can be hard, and some of us trim
> the mail history after a few days.
>
> So, basically, that paragraph should just read:
>
> ---8<---
> RESENDING YOUR REEDITED PATCHES:
>
> Go back to "CONTRIBUTING YOUR PATCHES".
> ---8<---
I did not understand this the first couple of times  I read it. I'd 
suggest more explicit wording.

+ RESUBMITTING MODIFIED PATCHES:

+Go back to "CONTRIBUTING YOUR PATCHES" and resubmit the full patch set.
> Apart that, patch is nice.
>
> Maybe you could also contribute this to the Hg WiKi, using a generic project
> name, and generic email adresses.
>
> Regards,
> Yann E. MORIN.

Regards.

--
For unsubscribe information see http://sourceware.org/lists.html#faq