[PATCH/RFC] Documentation/format-patch: summarize patch-sending workflow

[Jonathan Nieder <jrnieder@gmail.com>]

Hi Jim,

Jim Meyering wrote:

> I hope I haven't caused Junio or anyone else undue trouble.
> I know well how format-patch output can be used, but in the vast
> majority of patch-including messages I send, I include format-patch
> output mainly as an FYI, *following* commentary that does not
> belong in the log, so it's ok there -- desirable, even.

Sure, that's true.  The main problem with including a patch in mbox
format inline is that the "From " line tends to get corrupted.  How
about something like patch?

-- 8< --
Subject: Documentation/format-patch: summarize patch-sending workflow

Add a DISCUSSION section to encourage people to send patches in a
form that can be applied by "git am" automatically.  There are two
such forms:

 1. The default form in which most metadata goes in the mail header
    and the message body starts with the patch description;

 2. The snipsnip form in which a message starts with pertinent
    discussion and ends with a patch after a "scissors" mark.

While at it, include a pointer to Documentation/SubmittingPatches
for MUA-specific hints.

Inspired-by: Jim Meyering <jim@meyering.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-format-patch.txt |   48 +++++++++++++++++++++++++++++++++++-
 1 files changed, 47 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index a5525e9..5118fdb 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -274,9 +274,55 @@ as e-mailable patches:
 $ git format-patch -3
 ------------
 
+DISCUSSION
+----------
+The patch produced by 'git format-patch' is in UNIX mailbox format,
+like so:
+
+------------
+From f97e66080296c741200eacf1eaeb73f05b19e140 Mon Sep 17 00:00:00 2001
+From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= <avarab@gmail.com>
+Date: Sun, 10 Apr 2011 19:37:01 +0000
+Subject: [PATCH] Makefile: extract Q_() source strings as ngettext()
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+Content-Transfer-Encoding: 8bit
+
+The patch adding the Q_() wrapper function around ngettext[1] didn't
+contain a corresponding update to the "pot" target in the Makefile. As
+...
+------------
+
+Typically it will be placed in a MUA's drafts folder, edited to add
+timely commentary that should not go in the changelog after the three
+dashes, and then sent as a message whose body starts with "The patch
+adding the Q_() wrapper function ...".  On the receiving end, readers
+can save interesting patches in a UNIX mailbox and apply them with
+linkgit:git-am[1].
+
+'git am --scissors' accepts an alternative format with the patch
+inline in the message:
+
+------------
+...
+> So we should do such-and-such.
+
+Makes sense to me.  How about this patch?
+
+-- 8< --
+From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
+Subject: Makefile: extract Q_() source strings as ngettext()
+
+The patch adding the Q_() wrapper function around ngettext[1] didn't
+....
+------------
+
+See linkgit:git-am[1] for details.
+
 SEE ALSO
 --------
-linkgit:git-am[1], linkgit:git-send-email[1]
+linkgit:git-am[1], linkgit:git-send-email[1], linkgit:git-imap-send[1],
+Documentation/SubmittingPatches
 
 GIT
 ---
-- 
1.7.5.rc0