[PATCH/RFC] Documentation/format-patch: summarize patch-sending workflow
flat view
From: Jonathan Nieder <hidden>
Date: 2016-06-15 22:51:02
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
Possibly related (same subject, not in this thread)
- 2016-06-15 · Re: [PATCH/RFC] Documentation/format-patch: summarize patch-sending workflow · Junio C Hamano <hidden>
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 [off-list ref]
Signed-off-by: Jonathan Nieder <redacted>
---
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