[PATCH] Recommend correct way to submit new version of the patches.

[PATCH] Recommend correct way to submit new version of the patches.

[Subodh Nijsure]

Russell King suggested proper way to submit new versions of the patches.
See http://lists.infradead.org/pipermail/linux-arm-kernel/2012-April/096236.html
Modify SubmittingPatches to summerize that recommendation.

Signed-off-by: Subodh Nijsure <snijsure@grid-net.com>
---
 Documentation/SubmittingPatches |   12 ++++++++++++
 1 files changed, 12 insertions(+), 0 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 4468ce2..4b166a4 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -579,6 +579,18 @@ use diffstat options "-p 1 -w 70" so that filenames are listed from
 the top of the kernel source tree and don't use too much horizontal
 space (easily fit in 80 columns, maybe with some indentation).
 
+Please don't thread the posting of a new version of the patches to
+the previous posting of the older version.  In other words, the
+initial summary mail for Vn should not be threaded to the Vn-1
+series, and the individual patches for Vn should only be threaded
+to the initial summary mail for Vn. This is to avoid one massive
+thread for a proposed patch.
+
+If you wish to provide a direct reference back to a previous thread,
+please do so via URLs into archives, or providing the message id or
+exact subject of the previous series in the new summary message body.
+But please don't thread each version to the previous version!
+
 See more details on the proper patch format in the following
 references.
 
-- 
1.7.5.4

Re: [PATCH] Recommend correct way to submit new version of the patches.

[Rob Landley]

On 04/25/2012 04:51 PM, Subodh Nijsure wrote:
> Russell King suggested proper way to submit new versions of the patches.
> See http://lists.infradead.org/pipermail/linux-arm-kernel/2012-April/096236.html
> Modify SubmittingPatches to summerize that recommendation.
> 
> Signed-off-by: Subodh Nijsure <snijsure@grid-net.com>
> ---
>  Documentation/SubmittingPatches |   12 ++++++++++++
>  1 files changed, 12 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 4468ce2..4b166a4 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -579,6 +579,18 @@ use diffstat options "-p 1 -w 70" so that filenames are listed from
>  the top of the kernel source tree and don't use too much horizontal
>  space (easily fit in 80 columns, maybe with some indentation).
>  
> +Please don't thread the posting of a new version of the patches to
> +the previous posting of the older version.

I prefer documentation emphasize "Do X" rather than "Don't do X".

> In other words, the
> +initial summary mail for Vn should not be threaded to the Vn-1
> +series,

They should instead be in reply to some _other_ random message?

> and the individual patches for Vn should only be threaded
> +to the initial summary mail for Vn.

They can be threaded to more than one thing at a time?

> +This is to avoid one massive
> +thread for a proposed patch.
> +
> +If you wish to provide a direct reference back to a previous thread,
> +please do so via URLs into archives, or providing the message id or
> +exact subject of the previous series in the new summary message body.

If you're going to give the subject, give the date it was posted.

> +But please don't thread each version to the previous version!

Repeating your topic sentence with an exclamation point at the end
doesn't really help matters here.

Would you like me to take a stab at wordsmithing this? Something like:

  Each patch series should ideally start with a 0/X summary message
  explaining the purpose of the series, with each Y/X message posted as
  a reply to that summary.

  Post each new version of a patch series as its own thread. This avoids
  unmanageably long threads and burying new activity in old threads
  where it's less likely to be noticed. To reference a previous series,
  give a URL to a web archive, or provide the message ID, or the
  subject line and date of the previous posting.

(The existing context doesn't even mention 0/5 summary messages, and the
hunk about "When you submit or resubmit" is up at line 101 rather than
down in the 580's...)

Rob
-- 
GNU/Linux isn't: Linux=GPLv2, GNU=GPLv3+, they can't share code.
Either it's "mere aggregation", or a license violation.  Pick one.

Re: [PATCH] Recommend correct way to submit new version of the patches.

[Subodh Nijsure]

Hello Rob,

On 04/26/2012 09:43 AM, Rob Landley wrote:
> On 04/25/2012 04:51 PM, Subodh Nijsure wrote:
>> Russell King suggested proper way to submit new versions of the patches.
>> See http://lists.infradead.org/pipermail/linux-arm-kernel/2012-April/096236.html
>> Modify SubmittingPatches to summerize that recommendation.
>>
>> Signed-off-by: Subodh Nijsure<snijsure@grid-net.com>
>> ---
>>   Documentation/SubmittingPatches |   12 ++++++++++++
>>   1 files changed, 12 insertions(+), 0 deletions(-)
>>
>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
>> index 4468ce2..4b166a4 100644
>> --- a/Documentation/SubmittingPatches
>> +++ b/Documentation/SubmittingPatches
>> @@ -579,6 +579,18 @@ use diffstat options "-p 1 -w 70" so that filenames are listed from
>>   the top of the kernel source tree and don't use too much horizontal
>>   space (easily fit in 80 columns, maybe with some indentation).
>>
>> +Please don't thread the posting of a new version of the patches to
>> +the previous posting of the older version.
> I prefer documentation emphasize "Do X" rather than "Don't do X".
>
>> In other words, the
>> +initial summary mail for Vn should not be threaded to the Vn-1
>> +series,
> They should instead be in reply to some _other_ random message?
>
>> and the individual patches for Vn should only be threaded
>> +to the initial summary mail for Vn.
> They can be threaded to more than one thing at a time?
>
>> +This is to avoid one massive
>> +thread for a proposed patch.
>> +
>> +If you wish to provide a direct reference back to a previous thread,
>> +please do so via URLs into archives, or providing the message id or
>> +exact subject of the previous series in the new summary message body.
> If you're going to give the subject, give the date it was posted.
>
>> +But please don't thread each version to the previous version!
> Repeating your topic sentence with an exclamation point at the end
> doesn't really help matters here.
>
> Would you like me to take a stab at wordsmithing this? Something like:
>
>    Each patch series should ideally start with a 0/X summary message
>    explaining the purpose of the series, with each Y/X message posted as
>    a reply to that summary.
>
>    Post each new version of a patch series as its own thread. This avoids
>    unmanageably long threads and burying new activity in old threads
>    where it's less likely to be noticed. To reference a previous series,
>    give a URL to a web archive, or provide the message ID, or the
>    subject line and date of the previous posting.
>
> (The existing context doesn't even mention 0/5 summary messages, and the
> hunk about "When you submit or resubmit" is up at line 101 rather than
> down in the 580's...)
I struggled with putting those two paragraph up at line 101 or in 
section that describes canonical patch format, decided on the later.

Never been good at word-smithing.
I have struggled with how does one submit patch reversions and Russell 
King described it very well on arm-linux mailing list and I thought we 
should capture this in documentation to help others that are just 
getting started with the process. Do you want me to submit v2 or you 
have it?

Regards,
/Subodh

Re: [PATCH] Recommend correct way to submit new version of the patches.

[Rob Landley]

On 04/26/2012 01:02 PM, Subodh Nijsure wrote:
...
>> Would you like me to take a stab at wordsmithing this? Something like:
>>
>>    Each patch series should ideally start with a 0/X summary message
>>    explaining the purpose of the series, with each Y/X message posted as
>>    a reply to that summary.
>>
>>    Post each new version of a patch series as its own thread. This avoids
>>    unmanageably long threads and burying new activity in old threads
>>    where it's less likely to be noticed. To reference a previous series,
>>    give a URL to a web archive, or provide the message ID, or the
>>    subject line and date of the previous posting.
>>
>> (The existing context doesn't even mention 0/5 summary messages, and the
>> hunk about "When you submit or resubmit" is up at line 101 rather than
>> down in the 580's...)
> I struggled with putting those two paragraph up at line 101 or in
> section that describes canonical patch format, decided on the later.

Maybe the file will someday need structural cleanup so there's one
obvious place to put this, but that's beyond the scope of this patch.

> Never been good at word-smithing.
> I have struggled with how does one submit patch reversions and Russell
> King described it very well on arm-linux mailing list and I thought we
> should capture this in documentation to help others that are just
> getting started with the process. Do you want me to submit v2 or you
> have it?

Did my rephrase capture what you wanted to say?

Rob
-- 
GNU/Linux isn't: Linux=GPLv2, GNU=GPLv3+, they can't share code.
Either it's "mere aggregation", or a license violation.  Pick one.