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

["Yann E. MORIN" <yann dot morin dot 1998 at anciens dot enib dot fr>]

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.

  '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<---

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.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'



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