[PATCH RESEND 1/3] SubmittingPatches: Add style recommendation to use imperative descriptions

[PATCH RESEND 1/3] SubmittingPatches: Add style recommendation to use imperative descriptions

[Josh Triplett]

Most commit messages use this style, and the recommendation frequently
comes up in discussions (especially in response to patches that don't
use it), but that recommendation doesn't actually appear anywhere in
Documentation.  Add this style guideline to SubmittingPatches, using the
description from git's SubmittingPatches.

Signed-off-by: Josh Triplett <josh@joshtriplett.org>
Acked-by: Borislav Petkov <bp@suse.de>
---
 Documentation/SubmittingPatches | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 26b1e31..c74e73c 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -106,6 +106,11 @@ I.e., the patch (series) and its description should be self-contained.
 This benefits both the patch merger(s) and reviewers.  Some reviewers
 probably didn't even receive earlier versions of the patch.
 
+Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
+instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
+to do frotz", as if you are giving orders to the codebase to change
+its behaviour.
+
 If the patch fixes a logged bug entry, refer to that bug entry by
 number and URL.
 
-- 
1.9.0

[PATCH RESEND 2/3] SubmittingPatches: Add recommendation for mailing list references

[Josh Triplett]

SubmittingPatches already mentions referencing bugs fixed by a commit,
but doesn't mention citing relevant mailing list discussions.  Add a
note to that effect, along with a recommendation to use the
https://lkml.kernel.org/ redirector.

Portions based on text from git's SubmittingPatches.

Signed-off-by: Josh Triplett <josh@joshtriplett.org>
Acked-by: Borislav Petkov <bp@suse.de>
---
 Documentation/SubmittingPatches | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index c74e73c..53e6590 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -112,7 +112,15 @@ to do frotz", as if you are giving orders to the codebase to change
 its behaviour.
 
 If the patch fixes a logged bug entry, refer to that bug entry by
-number and URL.
+number and URL.  If the patch follows from a mailing list discussion,
+give a URL to the mailing list archive; use the https://lkml.kernel.org/
+redirector with a Message-Id, to ensure that the links cannot become
+stale.
+
+However, try to make your explanation understandable without external
+resources.  In addition to giving a URL to a mailing list archive or
+bug, summarize the relevant points of the discussion that led to the
+patch as submitted.
 
 If you want to refer to a specific commit, don't just refer to the
 SHA-1 ID of the commit. Please also include the oneline summary of
-- 
1.9.0

[PATCH RESEND 3/3] SubmittingPatches: Document the use of git

[Josh Triplett]

Most of the mechanical portions of SubmittingPatches exist to help patch
submitters replicate the output of git.  Mention this explicitly, both
as a reminder that git will help with this process, and as signposting to
let git users know what they can safely skip.

Signed-off-by: Josh Triplett <josh@joshtriplett.org>
Acked-by: Borislav Petkov <bp@suse.de>
---
 Documentation/SubmittingPatches | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 53e6590..fdad7d1 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -14,7 +14,10 @@ Read Documentation/SubmitChecklist for a list of items to check
 before submitting code.  If you are submitting a driver, also read
 Documentation/SubmittingDrivers.
 
-
+Many of these steps describe the default behavior of the git version
+control system; if you use git to prepare your patches, you'll find much
+of the mechanical work done for you, though you'll still need to prepare
+and document a sensible set of patches.
 
 --------------------------------------------
 SECTION 1 - CREATING AND SENDING YOUR CHANGE
@@ -25,7 +28,9 @@ SECTION 1 - CREATING AND SENDING YOUR CHANGE
 1) "diff -up"
 ------------
 
-Use "diff -up" or "diff -uprN" to create patches.
+Use "diff -up" or "diff -uprN" to create patches.  git generates patches
+in this form by default; if you're using git, you can skip this section
+entirely.
 
 All changes to the Linux kernel occur in the form of patches, as
 generated by diff(1).  When creating your patch, make sure to create it
@@ -66,19 +71,14 @@ Make sure your patch does not include any extra files which do not
 belong in a patch submission.  Make sure to review your patch -after-
 generated it with diff(1), to ensure accuracy.
 
-If your changes produce a lot of deltas, you may want to look into
-splitting them into individual patches which modify things in
-logical stages.  This will facilitate easier reviewing by other
-kernel developers, very important if you want your patch accepted.
-There are a number of scripts which can aid in this:
-
-Quilt:
-http://savannah.nongnu.org/projects/quilt
+If your changes produce a lot of deltas, you need to split them into
+individual patches which modify things in logical stages; see section
+#3.  This will facilitate easier reviewing by other kernel developers,
+very important if you want your patch accepted.
 
-Andrew Morton's patch scripts:
-http://userweb.kernel.org/~akpm/stuff/patch-scripts.tar.gz
-Instead of these scripts, quilt is the recommended patch management
-tool (see above).
+If you're using git, "git rebase -i" can help you with this process.  If
+you're not using git, quilt <http://savannah.nongnu.org/projects/quilt>
+is another popular alternative.
 
 
 
@@ -607,7 +607,8 @@ patch.
 If you are going to include a diffstat after the "---" marker, please
 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).
+space (easily fit in 80 columns, maybe with some indentation).  (git
+generates appropriate diffstats by default.)
 
 See more details on the proper patch format in the following
 references.
-- 
1.9.0

Re: [PATCH RESEND 2/3] SubmittingPatches: Add recommendation for mailing list references

[Randy Dunlap]

On 02/22/2014 12:12 PM, Josh Triplett wrote:
> SubmittingPatches already mentions referencing bugs fixed by a commit,
> but doesn't mention citing relevant mailing list discussions.  Add a
> note to that effect, along with a recommendation to use the
> https://lkml.kernel.org/ redirector.
> 
> Portions based on text from git's SubmittingPatches.
> 
> Signed-off-by: Josh Triplett <josh@joshtriplett.org>
> Acked-by: Borislav Petkov <bp@suse.de>
> ---
>  Documentation/SubmittingPatches | 10 +++++++++-
>  1 file changed, 9 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index c74e73c..53e6590 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -112,7 +112,15 @@ to do frotz", as if you are giving orders to the codebase to change
>  its behaviour.
>  
>  If the patch fixes a logged bug entry, refer to that bug entry by
> -number and URL.
> +number and URL.  If the patch follows from a mailing list discussion,
> +give a URL to the mailing list archive; use the https://lkml.kernel.org/
> +redirector with a Message-Id, to ensure that the links cannot become
> +stale.

Some of us don't know what that looks like.
Could we have an example?

> +However, try to make your explanation understandable without external
> +resources.  In addition to giving a URL to a mailing list archive or
> +bug, summarize the relevant points of the discussion that led to the
> +patch as submitted.
>  
>  If you want to refer to a specific commit, don't just refer to the
>  SHA-1 ID of the commit. Please also include the oneline summary of
> 


-- 
~Randy

Re: [PATCH RESEND 2/3] SubmittingPatches: Add recommendation for mailing list references

[Josh Triplett]

On Sat, Feb 22, 2014 at 01:56:54PM -0800, Randy Dunlap wrote:
> On 02/22/2014 12:12 PM, Josh Triplett wrote:
> > SubmittingPatches already mentions referencing bugs fixed by a commit,
> > but doesn't mention citing relevant mailing list discussions.  Add a
> > note to that effect, along with a recommendation to use the
> > https://lkml.kernel.org/ redirector.
> > 
> > Portions based on text from git's SubmittingPatches.
> > 
> > Signed-off-by: Josh Triplett <josh@joshtriplett.org>
> > Acked-by: Borislav Petkov <bp@suse.de>
> > ---
> >  Documentation/SubmittingPatches | 10 +++++++++-
> >  1 file changed, 9 insertions(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> > index c74e73c..53e6590 100644
> > --- a/Documentation/SubmittingPatches
> > +++ b/Documentation/SubmittingPatches
> > @@ -112,7 +112,15 @@ to do frotz", as if you are giving orders to the codebase to change
> >  its behaviour.
> >  
> >  If the patch fixes a logged bug entry, refer to that bug entry by
> > -number and URL.
> > +number and URL.  If the patch follows from a mailing list discussion,
> > +give a URL to the mailing list archive; use the https://lkml.kernel.org/
> > +redirector with a Message-Id, to ensure that the links cannot become
> > +stale.
> 
> Some of us don't know what that looks like.
> Could we have an example?

https://lkml.kernel.org/ provides examples; I didn't want to duplicate
that documentation.

- Josh Triplett

Re: [PATCH RESEND 2/3] SubmittingPatches: Add recommendation for mailing list references

[Borislav Petkov]

On Sat, Feb 22, 2014 at 02:30:38PM -0800, Josh Triplett wrote:
> > >  If the patch fixes a logged bug entry, refer to that bug entry by
> > > -number and URL.
> > > +number and URL.  If the patch follows from a mailing list discussion,
> > > +give a URL to the mailing list archive; use the https://lkml.kernel.org/
> > > +redirector with a Message-Id, to ensure that the links cannot become
> > > +stale.
> > 
> > Some of us don't know what that looks like.
> > Could we have an example?
> 
> https://lkml.kernel.org/ provides examples; I didn't want to duplicate
> that documentation.

Yeah, maybe you should say:

"If the patch follows from a mailing list discussion, give a URL to the
mailing list archive; use the https://lkml.kernel.org/ (usage examples
at that very URL) ... "

so that it is crystal clear.

-- 
Regards/Gruss,
    Boris.

Sent from a fat crate under my desk. Formatting is fine.
--

Re: [PATCH RESEND 2/3] SubmittingPatches: Add recommendation for mailing list references

[Randy Dunlap]

On 02/22/2014 02:30 PM, Josh Triplett wrote:
> On Sat, Feb 22, 2014 at 01:56:54PM -0800, Randy Dunlap wrote:
>> On 02/22/2014 12:12 PM, Josh Triplett wrote:
>>> SubmittingPatches already mentions referencing bugs fixed by a commit,
>>> but doesn't mention citing relevant mailing list discussions.  Add a
>>> note to that effect, along with a recommendation to use the
>>> https://lkml.kernel.org/ redirector.
>>>
>>> Portions based on text from git's SubmittingPatches.
>>>
>>> Signed-off-by: Josh Triplett <josh@joshtriplett.org>
>>> Acked-by: Borislav Petkov <bp@suse.de>
>>> ---
>>>  Documentation/SubmittingPatches | 10 +++++++++-
>>>  1 file changed, 9 insertions(+), 1 deletion(-)
>>>
>>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
>>> index c74e73c..53e6590 100644
>>> --- a/Documentation/SubmittingPatches
>>> +++ b/Documentation/SubmittingPatches
>>> @@ -112,7 +112,15 @@ to do frotz", as if you are giving orders to the codebase to change
>>>  its behaviour.
>>>  
>>>  If the patch fixes a logged bug entry, refer to that bug entry by
>>> -number and URL.
>>> +number and URL.  If the patch follows from a mailing list discussion,
>>> +give a URL to the mailing list archive; use the https://lkml.kernel.org/
>>> +redirector with a Message-Id, to ensure that the links cannot become
>>> +stale.
>>
>> Some of us don't know what that looks like.
>> Could we have an example?
> 
> https://lkml.kernel.org/ provides examples; I didn't want to duplicate
> that documentation.

Thanks, I didn't know that and wouldn't normally look there to see if
it provides examples, so you could do like Boris suggested... :)


-- 
~Randy