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

[wino]

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