[PATCH] Documentation/email-clients.txt: discuss In-Reply-To

[PATCH] Documentation/email-clients.txt: discuss In-Reply-To

[Chris Metcalf]

In-Reply-To: <20151023090459.GW17308@twins.programming.kicks-ass.net>

This commit adds a paragraph suggesting best practices for
when to link patches to previous LKML messages via In-Reply-To.

Signed-off-by: Chris Metcalf <cmetcalf@ezchip.com>
---
 Documentation/email-clients.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt
index 3fa450881ecb..547c54a2f4e0 100644
--- a/Documentation/email-clients.txt
+++ b/Documentation/email-clients.txt
@@ -39,6 +39,16 @@ you avoid some possible charset problems.
 Email clients should generate and maintain References: or In-Reply-To:
 headers so that mail threading is not broken.
 
+When manually adding In-Reply-To: headers to a patch (e.g., using `git
+send email`), use common sense to associate the patch with previous
+relevant discussion, e.g. link a bug fix to the email with the bug report.
+For a multi-patch series, it is generally best to avoid using
+In-Reply-To: to link to older versions of the series.  This way
+multiple versions of the patch don't become an unmanageable forest of
+references in email clients.  If a link is helpful, you can use an
+"http://lkml.kernel.org/r/MESSAGEID" URL (e.g., in the cover email
+text) to link to an earlier version of the patch series.
+
 Copy-and-paste (or cut-and-paste) usually does not work for patches
 because tabs are converted to spaces.  Using xclipboard, xclip, and/or
 xcutsel may work, but it's best to test this for yourself or just avoid
-- 
2.1.2

Re: [PATCH] Documentation/email-clients.txt: discuss In-Reply-To

[Jonathan Corbet]

On Fri, 23 Oct 2015 12:13:01 -0400
Chris Metcalf <cmetcalf@ezchip.com> wrote:

> +When manually adding In-Reply-To: headers to a patch (e.g., using `git
> +send email`), use common sense to associate the patch with previous
> +relevant discussion, e.g. link a bug fix to the email with the bug report.
> +For a multi-patch series, it is generally best to avoid using
> +In-Reply-To: to link to older versions of the series.  This way
> +multiple versions of the patch don't become an unmanageable forest of
> +references in email clients.  If a link is helpful, you can use an
> +"http://lkml.kernel.org/r/MESSAGEID" URL (e.g., in the cover email
> +text) to link to an earlier version of the patch series.

So this is sitting in my docs folder waiting to see if anybody else had
anything to say.  Nope.  I guess I'm not opposed to this addition, but
I'm not quite sure what problem is being solved.  Is there a plague of
inappropriate hand-crafted In-Reply-To headers out there that I've not
seen?

Beyond that, this seems like advice that is better put into
SubmittingPatches if we really want it.

Thanks,

jon

Re: [PATCH] Documentation/email-clients.txt: discuss In-Reply-To

[Chris Metcalf]

On 11/05/2015 01:31 PM, Jonathan Corbet wrote:
> On Fri, 23 Oct 2015 12:13:01 -0400
> Chris Metcalf <cmetcalf@ezchip.com> wrote:
>
>> +When manually adding In-Reply-To: headers to a patch (e.g., using `git
>> +send email`), use common sense to associate the patch with previous
>> +relevant discussion, e.g. link a bug fix to the email with the bug report.
>> +For a multi-patch series, it is generally best to avoid using
>> +In-Reply-To: to link to older versions of the series.  This way
>> +multiple versions of the patch don't become an unmanageable forest of
>> +references in email clients.  If a link is helpful, you can use an
>> +"http://lkml.kernel.org/r/MESSAGEID" URL (e.g., in the cover email
>> +text) to link to an earlier version of the patch series.
> So this is sitting in my docs folder waiting to see if anybody else had
> anything to say.  Nope.  I guess I'm not opposed to this addition, but
> I'm not quite sure what problem is being solved.  Is there a plague of
> inappropriate hand-crafted In-Reply-To headers out there that I've not
> seen?

The "git help send-email" documentation for "--in-reply-to" suggests
building hand-crafted In-Reply-To headers this way for subsequent
versions of patch series. This paragraph is intended to suggest that's
a bad idea.

> Beyond that, this seems like advice that is better put into
> SubmittingPatches if we really want it.

That was my original thought, but Peter suggested email-clients.txt:

lkml.kernel.org/r/20151023090459.GW17308@twins.programming.kicks-ass.net

-- 
Chris Metcalf, EZChip Semiconductor
http://www.ezchip.com

Re: [PATCH] Documentation/email-clients.txt: discuss In-Reply-To

[Steven Rostedt]

On Thu, 5 Nov 2015 14:11:48 -0500
Chris Metcalf <cmetcalf@ezchip.com> wrote:

> On 11/05/2015 01:31 PM, Jonathan Corbet wrote:
> > On Fri, 23 Oct 2015 12:13:01 -0400
> > Chris Metcalf <cmetcalf@ezchip.com> wrote:
> >
> >> +When manually adding In-Reply-To: headers to a patch (e.g., using `git
> >> +send email`), use common sense to associate the patch with previous
> >> +relevant discussion, e.g. link a bug fix to the email with the bug report.
> >> +For a multi-patch series, it is generally best to avoid using
> >> +In-Reply-To: to link to older versions of the series.  This way
> >> +multiple versions of the patch don't become an unmanageable forest of
> >> +references in email clients.  If a link is helpful, you can use an
> >> +"http://lkml.kernel.org/r/MESSAGEID" URL (e.g., in the cover email
> >> +text) to link to an earlier version of the patch series.
> > So this is sitting in my docs folder waiting to see if anybody else had
> > anything to say.  Nope.  I guess I'm not opposed to this addition, but
> > I'm not quite sure what problem is being solved.  Is there a plague of
> > inappropriate hand-crafted In-Reply-To headers out there that I've not
> > seen?
> 
> The "git help send-email" documentation for "--in-reply-to" suggests
> building hand-crafted In-Reply-To headers this way for subsequent
> versions of patch series. This paragraph is intended to suggest that's
> a bad idea.
> 
> > Beyond that, this seems like advice that is better put into
> > SubmittingPatches if we really want it.
> 
> That was my original thought, but Peter suggested email-clients.txt:
> 
> lkml.kernel.org/r/20151023090459.GW17308@twins.programming.kicks-ass.net
> 

Peter said "maybe". I would think keeping this in SubmittingPatches
would be better, as that's the one place we point people to to read
(and I should re-read).

-- Steve

[PATCH v2] Documentation/SubmittingPatches: discuss In-Reply-To

[Chris Metcalf]

Add a paragraph suggesting best practices for when to link patches
to previous LKML messages via In-Reply-To.

Signed-off-by: Chris Metcalf <cmetcalf@ezchip.com>
---
 Documentation/SubmittingPatches | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index fd89b04d34f0..9f61620f34ef 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -675,6 +675,16 @@ A couple of example Subjects:
     Subject: [patch 2/5] ext2: improve scalability of bitmap searching
     Subject: [PATCHv2 001/207] x86: fix eflags tracking
 
+It can be helpful to manually add In-Reply-To: headers to a patch
+(e.g., when using "git send email") to associate the patch with
+previous relevant discussion, e.g. to link a bug fix to the email with
+the bug report.  However, for a multi-patch series, it is generally
+best to avoid using In-Reply-To: to link to older versions of the
+series.  This way multiple versions of the patch don't become an
+unmanageable forest of references in email clients.  If a link is
+helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in
+the cover email text) to link to an earlier version of the patch series.
+
 The "from" line must be the very first line in the message body,
 and has the form:
 
-- 
2.1.2

Re: [PATCH v2] Documentation/SubmittingPatches: discuss In-Reply-To

[Frederic Weisbecker]

On Thu, Nov 05, 2015 at 03:21:47PM -0500, Chris Metcalf wrote:
> Add a paragraph suggesting best practices for when to link patches
> to previous LKML messages via In-Reply-To.
> 
> Signed-off-by: Chris Metcalf <cmetcalf@ezchip.com>

ACK!

Thanks!

> ---
>  Documentation/SubmittingPatches | 10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index fd89b04d34f0..9f61620f34ef 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -675,6 +675,16 @@ A couple of example Subjects:
>      Subject: [patch 2/5] ext2: improve scalability of bitmap searching
>      Subject: [PATCHv2 001/207] x86: fix eflags tracking
>  
> +It can be helpful to manually add In-Reply-To: headers to a patch
> +(e.g., when using "git send email") to associate the patch with
> +previous relevant discussion, e.g. to link a bug fix to the email with
> +the bug report.  However, for a multi-patch series, it is generally
> +best to avoid using In-Reply-To: to link to older versions of the
> +series.  This way multiple versions of the patch don't become an
> +unmanageable forest of references in email clients.  If a link is
> +helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in
> +the cover email text) to link to an earlier version of the patch series.
> +
>  The "from" line must be the very first line in the message body,
>  and has the form:
>  
> -- 
> 2.1.2
> 

Re: [PATCH v2] Documentation/SubmittingPatches: discuss In-Reply-To

[Jonathan Corbet]

On Thu, 5 Nov 2015 15:21:47 -0500
Chris Metcalf <cmetcalf@ezchip.com> wrote:

> Add a paragraph suggesting best practices for when to link patches
> to previous LKML messages via In-Reply-To.

We're getting there, but in the middle of the discussion on the format of
the patch itself seems like the wrong place.  So I've applied this, but I
took the liberty of moving the new paragraph into its own section.

Thanks,

jon

Re: [PATCH v2] Documentation/SubmittingPatches: discuss In-Reply-To

[Chris Metcalf]

On 11/11/2015 12:07 PM, Jonathan Corbet wrote:
> On Thu, 5 Nov 2015 15:21:47 -0500
> Chris Metcalf <cmetcalf@ezchip.com> wrote:
>
>> Add a paragraph suggesting best practices for when to link patches
>> to previous LKML messages via In-Reply-To.
> We're getting there, but in the middle of the discussion on the format of
> the patch itself seems like the wrong place.  So I've applied this, but I
> took the liberty of moving the new paragraph into its own section.

Great, thanks!

-- 
Chris Metcalf, EZChip Semiconductor
http://www.ezchip.com