Skip to contentSkip to conversation

Linux kernel patch submission format

DOC Jeff Garzik 11 participants 18 messages Aug 31, 2004 – Oct 21, 2004

lore
Share & tools
lore
#0 lore raw

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

#1 lore raw
Quoted 12 lines · 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

Quoted 5 lines

-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
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

Signature · 8 lines
/***************************************************
 *Neil Horman
 *Software Engineer
 *Red Hat, Inc.
 *[email protected]
 *gpg keyid: 1024D / 0x92A74FA1
 *http://pgp.mit.edu
 ***************************************************/
#2 lore raw
In reply to Jeff Garzik
Quoted 4 lines · 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

Looks good.

Quoted 2 lines

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

Signature · 2 lines
+-- Erik Mouw -- www.harddisk-recovery.com -- +31 70 370 12 90 --
| Lab address: Delftechpark 26, 2628 XH, Delft, The Netherlands
#3 lore raw
In reply to Jeff Garzik
Quoted 4 lines · 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

patch-format.html renamed from patch-format.html.orig +9 -0
@@ -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
Signature · 1 line
dwmw2
#4 lore raw
Quoted 5 lines · David Woodhouse
patch-format.html renamed from patch-format.html.orig +0 -0
@@ -83,6 +83,15 @@
 for the 5th time, resist the urge to attach 20 patches to a single
 email.

patch-format.html line 94

Quoted 10 lines
patch-format.html renamed from patch-format.html.orig +9 -0
 
+</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

#5 lore raw
Quoted 4 lines · Jeff Garzik

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 2004-08-31 18:16:14.042804288 +0100 renamed from patch-format.html.orig 2004-08-31 17:30:55.867029816 +0100 +3 -1
@@ -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>
 
Signature · 1 line
dwmw2
#7 lore raw
In reply to David Woodhouse
Quoted 11 lines · David Woodhouse
Quoted 4 lines · Jeff Garzik

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 2004-08-31 18:16:14.042804288 +0100 line 89

Quoted 10 lines
patch-format.html 2004-08-31 18:16:14.042804288 +0100 renamed from patch-format.html.orig 2004-08-31 17:30:55.867029816 +0100 +3 -1
@@ -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_FAQupdated.htm renamed from LKML_FAQ.htm +8 -12
@@ -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

#8 lore raw
In reply to Jeff Garzik

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?

#9 lore raw
Quoted 3 lines · Timothy Miller

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...

Signature · 4 lines
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
#10 lore raw
Quoted 1 line

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

Signature · 3 lines
                          I won't rest till it's the best ...
                          Programmer, Linux Scalability
                          Paul Jackson <[email protected]> 1.650.933.1373
#11 lore raw
In reply to Horst von Brand
Quoted 6 lines · Horst von Brand
Quoted 1 line · Timothy Miller

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?

#12 lore raw

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

| 
| 
| Horst von Brand wrote:
| > Timothy Miller <[email protected]> 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)

#13 lore raw
Quoted 8 lines · Randy.Dunlap

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

| | | Horst von Brand wrote:
| > Timothy Miller <[email protected]> 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?
Quoted 4 lines

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. :)

#15 lore raw
Quoted 5 lines · Sam Ravnborg

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

#16 lore raw
In reply to Jeff Garzik

Am Dienstag, 31. August 2004 10:08 schrieb Jeff Garzik:

Quoted 7 lines

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 2004-08-31 19:44:43.000000000 +0200 renamed from patch-format.html.orig 2004-08-31 19:43:33.000000000 +0200 +1 -1
@@ -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>
Signature · 5 lines
Patrick Dreker

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