[DOC] Linux kernel patch submission format

[DOC] Linux kernel patch submission format

[Jeff Garzik]

I tried to keep it as short as possible:  here is a page describing the 
most optimal format for sending patches to Linux kernel developers.

	http://linux.yyz.us/patch-format.html

This URL should be permanent, feel free to bookmark it.
Comments welcome.

	Jeff

Re: [DOC] Linux kernel patch submission format

[Neil Horman]

Jeff Garzik wrote:
> 
> I tried to keep it as short as possible:  here is a page describing the 
> most optimal format for sending patches to Linux kernel developers.
> 
>     http://linux.yyz.us/patch-format.html
> 
> This URL should be permanent, feel free to bookmark it.
> Comments welcome.
> 
>     Jeff
> 
> 
> 
> -
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/

So, this may already be asked and answered (apologies if it has), but is 
it worth gpg-signing submissions so that authenticity can be verified to 
some degree when a patch is posted (and for archival purposes)? I ask 
because this is whats done on the fedora extras channel when updates get 
pushed, and it seems like a reasonable addition to the process.
Neil

-- 
/***************************************************
  *Neil Horman
  *Software Engineer
  *Red Hat, Inc.
  *nhorman@redhat.com
  *gpg keyid: 1024D / 0x92A74FA1
  *http://pgp.mit.edu
  ***************************************************/

Re: [DOC] Linux kernel patch submission format

[Erik Mouw]

On Tue, Aug 31, 2004 at 04:08:21AM -0400, Jeff Garzik wrote:
> I tried to keep it as short as possible:  here is a page describing the 
> most optimal format for sending patches to Linux kernel developers.
> 
> 	http://linux.yyz.us/patch-format.html

Looks good.

> This URL should be permanent, feel free to bookmark it.
> Comments welcome.

What about including this in the kernel tarball itself so it can't get
lost? You could include it in Documentation/SubmittingPatches.


Erik

-- 
+-- Erik Mouw -- www.harddisk-recovery.com -- +31 70 370 12 90 --
| Lab address: Delftechpark 26, 2628 XH, Delft, The Netherlands

Re: [DOC] Linux kernel patch submission format

[David Woodhouse]

On Tue, 2004-08-31 at 04:08 -0400, Jeff Garzik wrote:
> I tried to keep it as short as possible:  here is a page describing the 
> most optimal format for sending patches to Linux kernel developers.
> 
> 	http://linux.yyz.us/patch-format.html

--- patch-format.html.orig
+++ patch-format.html
@@ -83,6 +83,15 @@
 for the 5th time, resist the urge to attach 20 patches to a single
 email.
 
+</li><li><h2>One thread per set of patches</h2>
+
+The corollary to the above rule: when sending more than one patch in
+separate emails, make sure they stay together. Send the second and
+subsequent mails as <em>replies</em> to the first mail, rather than
+having each one start its own thread. (You should also ensure that
+your mail client obeys RFC2822 by including correct
+<TT>References:</TT> headers in replies.)
+
 </li><li><h2>Sign your work</h2>
 
 The sign-off is a simple line at the end of the explanation for the

-- 
dwmw2

Re: [DOC] Linux kernel patch submission format

[Sam Ravnborg]

Suggested:
[PATCH $version $n/$total] one-line summary

Preferable:
[PATCH $version $n/$total] subsystem: one-line summary

	Sam

Re: [DOC] Linux kernel patch submission format

[Jeff Garzik]

Sam Ravnborg wrote:
> Suggested:
> [PATCH $version $n/$total] one-line summary
> 
> Preferable:
> [PATCH $version $n/$total] subsystem: one-line summary


The text says that subsystem is included in the one-line summary, but 
you're right...  I'll make it more clear.  Updated.

	Jeff

Re: [DOC] Linux kernel patch submission format

[Jeff Garzik]

David Woodhouse wrote:
> --- patch-format.html.orig
> +++ patch-format.html
> @@ -83,6 +83,15 @@
>  for the 5th time, resist the urge to attach 20 patches to a single
>  email.
>  
> +</li><li><h2>One thread per set of patches</h2>
> +
> +The corollary to the above rule: when sending more than one patch in
> +separate emails, make sure they stay together. Send the second and
> +subsequent mails as <em>replies</em> to the first mail, rather than
> +having each one start its own thread. (You should also ensure that
> +your mail client obeys RFC2822 by including correct
> +<TT>References:</TT> headers in replies.)
> +


hmmmm.  While I do agree with the content, I'm trying to avoid 
lengthening this page.  If we describe every little detail, then it 
becomes long -- just like SubmittingPatches -- and everybody will skip 
reading it.

	Jeff

Re: [DOC] Linux kernel patch submission format

[David Woodhouse]

On Tue, 2004-08-31 at 13:15 -0400, Jeff Garzik wrote:
> hmmmm.  While I do agree with the content, I'm trying to avoid 
> lengthening this page.  If we describe every little detail, then it 
> becomes long -- just like SubmittingPatches -- and everybody will skip 
> reading it.

Good point. How about cutting it down to this then:

--- patch-format.html.orig      2004-08-31 17:30:55.867029816 +0100
+++ patch-format.html   2004-08-31 18:16:14.042804288 +0100
@@ -81,7 +81,9 @@

 This cannot be stressed enough.  Even when you are resending a change
 for the 5th time, resist the urge to attach 20 patches to a single
-email.
+email. If you do send multiple emails though, make sure the second
+and subsequent emails are sent as replies to the first, to keep them
+all together in a thread.

 </li><li><h2>Sign your work</h2>


-- 
dwmw2

Re: [DOC] Linux kernel patch submission format

[Jeff Garzik]

applied

Re: [DOC] Linux kernel patch submission format

[Patrick Dreker]

Am Dienstag, 31. August 2004 10:08 schrieb Jeff Garzik:
> I tried to keep it as short as possible:  here is a page describing the
> most optimal format for sending patches to Linux kernel developers.
>
>  http://linux.yyz.us/patch-format.html
>
> This URL should be permanent, feel free to bookmark it.
> Comments welcome.

Small typo fixed

Patrick

--- patch-format.html.orig 2004-08-31 19:43:33.000000000 +0200
+++ patch-format.html 2004-08-31 19:44:43.000000000 +0200
@@ -51,7 +51,7 @@
 </pre>
 
 The "$n/$total" may be omitted if there is only one patch in the series.
-Writing "1/1" would is not necessary.
+Writing "1/1" is not necessary.
 
 
 <li><h2>Email body contents: description</h2>

-- 
Patrick Dreker

GPG KeyID  : 0xFCC2F7A7 (Patrick Dreker)
Fingerprint: 7A21 FC7F 707A C498 F370  1008 7044 66DA FCC2 F7A7
Key available from keyservers

Re: [DOC] Linux kernel patch submission format

[Jeff Garzik]

applied

Re: [DOC] Linux kernel patch submission format

[Lee Revell]

On Tue, 2004-08-31 at 13:17, David Woodhouse wrote:
> On Tue, 2004-08-31 at 13:15 -0400, Jeff Garzik wrote:
> > hmmmm.  While I do agree with the content, I'm trying to avoid 
> > lengthening this page.  If we describe every little detail, then it 
> > becomes long -- just like SubmittingPatches -- and everybody will skip 
> > reading it.
> 
> Good point. How about cutting it down to this then:
> 
> --- patch-format.html.orig      2004-08-31 17:30:55.867029816 +0100
> +++ patch-format.html   2004-08-31 18:16:14.042804288 +0100
> @@ -81,7 +81,9 @@
> 
>  This cannot be stressed enough.  Even when you are resending a change
>  for the 5th time, resist the urge to attach 20 patches to a single
> -email.
> +email. If you do send multiple emails though, make sure the second
> +and subsequent emails are sent as replies to the first, to keep them
> +all together in a thread.
> 
>  </li><li><h2>Sign your work</h2>
> 

This patch updates the FAQ to match the preferred method for submitting
large patches.  Rather than repeating the redundant paragraph, I removed
it.  Also Andrew Morton should really get credit for this entry, but he
is not in the Contributors list.

--- LKML_FAQ.htm	2004-08-31 19:18:45.000000000 -0400
+++ LKML_FAQupdated.htm	2004-08-31 21:23:31.000000000 -0400
@@ -1723,10 +1723,14 @@
 read your patch, and thus your patch will be deleted without comment.
 </LI>
 <LI>
-If you have a large patch, post a URL instead, otherwise you'll fill
-the mailboxes of thousands of people, and you will get complaints.
-Posting a new, large patch once might be OK, but updates should not be
-posted in full (post a URL).
+This FAQ previously advised posting a URL to a patch if the patch is large.
+This is no longer recommended.  The preferred way to submit a large patch is to 
+break it up into logical chunks, with a descriptive comment for each, and post 
+each piece with a subject line like "[PATCH] cleanup of foo driver [1/5]".
+Do not start a new thread for each chunk - rather, post each chunk as a followup 
+to the previous chunk.  You may want to begin with an explanatory post, and label 
+it something like "[PATCH] cleanup of foo driver [0/5]".  See 
+Documentation/SubmittingPatches for more information.
 </LI>
 <LI>
 If you want Linus or one of the primary maintainers (i.e. Marcelo,
@@ -3609,14 +3613,6 @@
 </LI>
 
 <LI>
-<FONT COLOR="#0000FF">(PG)</FONT> If your patch is on the large size
-(say larger than 500 lines) consider posting a URL pointing to the
-patch along with the patch description, instead of the whole patch. If
-you don't have a WWW site handy to put the patch on, then at least
-gzip it prior to attaching it to your post/patch description.
-</LI>
-
-<LI>
 <FONT COLOR="#0000FF">(REG)</FONT> Note that Linus does not read
 linux-kernel very much. So if you want him to see a patch, you will
 need to send it to him directly (say by Cc:ing him if you post to the

Lee

Re: [DOC] Linux kernel patch submission format

[Timothy Miller]

Stupid question:

Does the Linux kernel source tree include a shell script which will 
compare two trees, create patches, and ask the necessary questions so as 
to format the files correctly with all the right stuff?

Re: [DOC] Linux kernel patch submission format

[Horst von Brand]

Timothy Miller <miller@techsource.com> said:
> Does the Linux kernel source tree include a shell script which will 
> compare two trees, create patches, and ask the necessary questions so as 
> to format the files correctly with all the right stuff?

diff(1) does what you want...
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                     Fono: +56 32 654431
Universidad Tecnica Federico Santa Maria              +56 32 654239
Casilla 110-V, Valparaiso, Chile                Fax:  +56 32 797513

Re: [DOC] Linux kernel patch submission format

[Paul Jackson]

> diff(1) does what you want...

Not all he wanted.  There's more to a patch than the diff.

The following three documents explain how to submit patches to the
Linux kernel:

 1) Documentation/SubmittingPatches, a file in the kernel source
 2) Andrew Morton's "The Perfect Patch", available at:
      http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt
 3) Jeff Garzik's "Linux kernel patch submission format", at:
      http://linux.yyz.us/patch-format.html

-- 
                          I won't rest till it's the best ...
                          Programmer, Linux Scalability
                          Paul Jackson <pj@sgi.com> 1.650.933.1373

Re: [DOC] Linux kernel patch submission format

[Timothy Miller]

Horst von Brand wrote:
> Timothy Miller <miller@techsource.com> said:
> 
>>Does the Linux kernel source tree include a shell script which will 
>>compare two trees, create patches, and ask the necessary questions so as 
>>to format the files correctly with all the right stuff?
> 
> 
> diff(1) does what you want...

So, in addition to producing the difference, diff also asks you all the 
questions necessary for a Linux kernel submission, properly formats 
them, and adds them to the diff output?

Re: [DOC] Linux kernel patch submission format

[Randy.Dunlap]

On Fri, 24 Sep 2004 11:04:38 -0400 Timothy Miller wrote:

| 
| 
| Horst von Brand wrote:
| > Timothy Miller <miller@techsource.com> said:
| > 
| >>Does the Linux kernel source tree include a shell script which will 
| >>compare two trees, create patches, and ask the necessary questions so as 
| >>to format the files correctly with all the right stuff?
| > 
| > 
| > diff(1) does what you want...
| 
| So, in addition to producing the difference, diff also asks you all the 
| questions necessary for a Linux kernel submission, properly formats 
| them, and adds them to the diff output?

Of course not.  There is no script in the kernel tree that does
what you asked... but you probably knew that.

Is one really needed?  or maybe a GUI IDE is all that is required.


--
~Randy
MOTD:  Always include version info.
(Again.  Sometimes I think ln -s /usr/src/linux/.config .signature)

Re: [DOC] Linux kernel patch submission format

[Timothy Miller]

Randy.Dunlap wrote:
> On Fri, 24 Sep 2004 11:04:38 -0400 Timothy Miller wrote:
> 
> | 
> | 
> | Horst von Brand wrote:
> | > Timothy Miller <miller@techsource.com> said:
> | > 
> | >>Does the Linux kernel source tree include a shell script which will 
> | >>compare two trees, create patches, and ask the necessary questions so as 
> | >>to format the files correctly with all the right stuff?
> | > 
> | > 
> | > diff(1) does what you want...
> | 
> | So, in addition to producing the difference, diff also asks you all the 
> | questions necessary for a Linux kernel submission, properly formats 
> | them, and adds them to the diff output?
> 
> Of course not.  There is no script in the kernel tree that does
> what you asked... but you probably knew that.
> 
> Is one really needed?  or maybe a GUI IDE is all that is required.

Yes, it's needed.

Rather than having a strict policy which many people are going to 
violate because they don't understand all the intricacies, it would be 
beneficial to have a script that everyone uses which enforces all the rules.

Among other things, this reduces confusion and the barrier to entry.

More patches will be acceptable, and no one will ever have to clean up a 
patch which is really important but just not formatted quite right.

Hey, think about it.  We're computer geeks who should understand very 
well how computers can be used as tools to automate processes, taking 
the burden off of humans.  Given that dozens of patches are posted every 
day, this seems like a prime candidate for automation!

Furthermore, the script can be written to do interesting and helpful 
things that no one would consider putting into the policy because they 
would be too bothersome for the user to do.

If I knew bash, perl, python, or any other scripting language, I would 
volunteer.  I don't think you'd like my horribly non-portable C or C++ 
version, and I don't think Verilog, PHP, or Javascript would quite do 
the job either.  :)