Revised [PATCH] Documentation: Update to SubmittingPatches

Revised [PATCH] Documentation: Update to SubmittingPatches

[Ian McDonald]

Updated documentation for submitting patches taking account of git.

Signed-off-by: Ian McDonald <imcdnzl@gmail.com>
---
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 237d54c..8756475 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -20,10 +20,24 @@ SECTION 1 - CREATING AND SENDING YOUR CH



-1) "diff -up"
-------------
+1) Creating a diff file
+-----------------------

-Use "diff -up" or "diff -uprN" to create patches.
+You can use git-diff(1) or git-format-patch(1) which makes your life easy. If
+you want it to be more difficult then carry on reading.
+
+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:
+
+Use "diff -up" or "diff -uprN" to create patches
+------------------------------------------------

 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
@@ -61,16 +75,6 @@ patch.  The "dontdiff" file is included
 2.6.12 and later.  For earlier kernel versions, you can get it
 from <http://www.xenotime.net/linux/doc/dontdiff>.

-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

Re: Revised [PATCH] Documentation: Update to SubmittingPatches

[Adrian Bunk]

On Wed, Dec 21, 2005 at 10:43:40AM +1300, Ian McDonald wrote:
> Updated documentation for submitting patches taking account of git.
> 
> Signed-off-by: Ian McDonald <imcdnzl@gmail.com>
> ---
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 237d54c..8756475 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -20,10 +20,24 @@ SECTION 1 - CREATING AND SENDING YOUR CH
> 
> 
> 
> -1) "diff -up"
> -------------
> +1) Creating a diff file
> +-----------------------
> 
> -Use "diff -up" or "diff -uprN" to create patches.
> +You can use git-diff(1) or git-format-patch(1) which makes your life easy. If
> +you want it to be more difficult then carry on reading.
>...

IMHO, this doesn't make much sense:

The average patch submitter does _not_ use git in any way - and there's 
no reason why he should.

cu
Adrian

-- 

       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed

Re: Revised [PATCH] Documentation: Update to SubmittingPatches

[Sean]

On Tue, January 10, 2006 7:57 pm, Adrian Bunk said:

>> -Use "diff -up" or "diff -uprN" to create patches.
>> +You can use git-diff(1) or git-format-patch(1) which makes your life
>> easy. If
>> +you want it to be more difficult then carry on reading.
>>...
>
> IMHO, this doesn't make much sense:
>
> The average patch submitter does _not_ use git in any way - and there's
> no reason why he should.
>

Git is an efficient and convenient way to track the mainline kernel.   The
number of submitters using it is significant enough to mention it as an
option for creating patches.

Sean

Re: Revised [PATCH] Documentation: Update to SubmittingPatches

[Adrian Bunk]

On Tue, Jan 10, 2006 at 08:38:23PM -0500, Sean wrote:
> On Tue, January 10, 2006 7:57 pm, Adrian Bunk said:
> 
> >> -Use "diff -up" or "diff -uprN" to create patches.
> >> +You can use git-diff(1) or git-format-patch(1) which makes your life
> >> easy. If
> >> +you want it to be more difficult then carry on reading.
> >>...
> >
> > IMHO, this doesn't make much sense:
> >
> > The average patch submitter does _not_ use git in any way - and there's
> > no reason why he should.
> >
> 
> Git is an efficient and convenient way to track the mainline kernel.   The
> number of submitters using it is significant enough to mention it as an
> option for creating patches.


<--  snip  -->

--------------------------------------------
SECTION 1 - CREATING AND SENDING YOUR CHANGE
--------------------------------------------

1) Creating a diff file
-----------------------

You can use git-diff(1) or git-format-patch(1) which makes your life easy. If
you want it to be more difficult then carry on reading.

<--  snip  -->


The first mentionings of the string "git" in the document are in this 
line.

SubmittingPatches should teach newbies how to create good patches with 
GNU diff, and random references to git programs don't help anyone.

If a submitter is using a git-based workflow he most likely has a 
comletely different wotkflow than the one described in SubmittingPatches -
and git-specific documents should cover what he should do.


> Sean

cu
Adrian

-- 

       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed

Re: Revised [PATCH] Documentation: Update to SubmittingPatches

[Junio C Hamano]

"Sean" <seanlkml@sympatico.ca> writes:

>> The average patch submitter does _not_ use git in any way - and there's
>> no reason why he should.
>
> Git is an efficient and convenient way to track the mainline kernel.   The
> number of submitters using it is significant enough to mention it as an
> option for creating patches.

I agree with Adrian on this point.  The
kernel-list patch reviewing process only depends on "diff -pu"
format, and git obviously gives its users an easy way to
generate such, but so would other tools.

The number of patches on the kernel list that are coming from
git does not really matter, but even if it did, they seem to be
a very small minority.

This is SubmittingPatches document that is being discussed, not
LinusPleasePull document.  The latter would naturally _require_
the developer to use git, but not the former.