Linux kernel patch submission format
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 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 ***************************************************/
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.
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
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.
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
Suggested:
[PATCH $version $n/$total] one-line summary
Preferable:
[PATCH $version $n/$total] subsystem: one-line summary
Sam
Quoted 5 lines · Sam Ravnborg
Suggested:
[PATCH $version $n/$total] one-line summaryPreferable:
[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
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
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
Jeff Garzik
Appliedapplied
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
Jeff Garzik
Appliedapplied
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
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?
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
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.1373Quoted 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?
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)
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. :)