Submitting Patches - Revision history

Sjhill: /* Verification */

2012-09-06T19:36:36Z

‎Verification

Sjhill at 19:36, 6 September 2012

2012-09-06T19:36:04Z

Sjhill: /* Delivery */

2012-09-06T19:23:44Z

‎Delivery

Sjhill at 19:23, 6 September 2012

2012-09-06T19:23:14Z

Sjhill: /* The Patch */

2012-09-06T19:22:39Z

‎The Patch

Sjhill at 19:22, 6 September 2012

2012-09-06T19:22:23Z

Sjhill: /* Generating the Patches */

2012-09-06T19:21:43Z

‎Generating the Patches

Sjhill: /* Subject */

2012-09-06T19:21:17Z

‎Subject

Sjhill: /* The diff */

2012-09-06T19:20:46Z

‎The diff

Sjhill: /* Changelog */

2012-09-06T19:18:05Z

‎Changelog

@@ Line 7: / Line 7: @@
 *Patches should be baselined against Linus' git repository, specifically whatever his latest <tt>-rcX</tt> tag is.
 *Patches should also be test merged against the <tt>upstream-sfr.git</tt> repository on branch <tt>mips-linux-next</tt>.
-*Finally, if any of your patches touch any files outside of the <tt>arch/mips</tt> directory, do a kernel build of any x86 architecture to make sure nothing gets broke from your patches.
+*Finally, if any of your patches touch files outside the <tt>arch/mips</tt> directory, do a kernel build of any x86 architecture to make sure nothing gets broke from your patches.
 == Subject ==

← Older revision		Revision as of 19:36, 6 September 2012
Line 1:		Line 1:
	This article is meant to help people to describe how to create, maintain and send patches that are easy to handle for the kernel maintainers.		This article is meant to help people to describe how to create, maintain and send patches that are easy to handle for the kernel maintainers.
		+
		+	== Verification ==
		+	Before generating patches for submittal, follow these steps:
		+	*Make sure each patch can be used with <tt>git bisect</tt>. This involves making sure each single patch applied separately allows other platforms to still be buildable and bootable.
		+	*The <tt>master</tt> branch of <tt>linux.git</tt> is simply the latest released code from Linus' upstream tree with any unmerged MIPS platform code mixed in. Do not use it to baseline patches against.
		+	*Patches should be baselined against Linus' git repository, specifically whatever his latest <tt>-rcX</tt> tag is.
		+	*Patches should also be test merged against the <tt>upstream-sfr.git</tt> repository on branch <tt>mips-linux-next</tt>.
		+	*Finally, if any of your patches touch any files outside of the <tt>arch/mips</tt> directory, do a kernel build of any x86 architecture to make sure nothing gets broke from your patches.

	== Subject ==		== Subject ==

@@ Line 23: / Line 23: @@
 All patches should be generated using the <code>git format-patch</code> command. No exceptions.
-== Delivery ==
+== Sending ==
 Patches are submitted via email only. Please read [[Mailing-patches]] for instructions once you have completed formatting your patches with git.

@@ Line 25: / Line 25: @@
 == Delivery ==
 Patches are submitted via email only. Please read [[Mailing-patches]] for instructions once you have completed formatting your patches with git.
 == Credits ==

@@ Line 20: / Line 20: @@
 *Add a Signed-off-by: line with your name and email address. If you are the person responsible for submitting patches for your group or company, you may have multiple Signed-off-by lines.
-== The Patch ==
+== Patch ==
 All patches should be generated using the <code>git format-patch</code> command. No exceptions.

@@ Line 1: / Line 1: @@
 This article is meant to help people to describe how to create, maintain and send patches that are easy to handle for the kernel maintainers.
 == Subject ==
 Each patch should have a subject that concisely describes the patch which the email contains.
 *It should not contain any filenames.
@@ Line 14: / Line 10: @@
 == Changelog ==
 Bear in mind that the changelog will also propagate all the way to Linus' tree. The changelog must describe the patch fully.
 *Here are some guidelines for changelog content:
@@ Line 21: / Line 16: @@
 **Implementation details.
 **Any testing results.
 *There is no point in mentioning what version of the kernel the patch applies to. This is not interesting information as once the patch is in git, it will probably be merged into a later kernel version than the one which you wrote it for anyway.
 *Do not refer to earlier patches in the changelog of a new version of a patch. It is not very useful to have a git changelog which says "OK, this fixes the things you mentioned yesterday". Each iteration of the patch should contain a standalone changelog.
@@ Line 29: / Line 23: @@
 All patches should be generated using the <code>git format-patch</code> command. No exceptions.
-== Overall ==
+== Delivery ==
 * Avoid MIME and attachements if possible.  Make sure that your email client does not wordwrap your patch.  Make sure that your email client does not replace tabs with spaces.  If you use a patch-corrupting mail clien tsuch as Firebird or Evolution, see the [[Mailing-patches|mailing patches]] for some hints.
 * Mail yourself a decent-sized patch and check that it still applies.

@@ Line 9: / Line 9: @@
 *It should not contain any filenames.
 *Do not use the same subject for every patch in a patch series. Bear in mind that the subject of your email becomes a globally-unique identifier for that patch. It will propagate all the way into Linus' git tree. The subject may later be used in developer discussions which refer to the patch and people will want the ability to Google for the patch's subject.
-*When [[Mailing-patches|sending]] a series of patches, the patches should be sequence numbered in the subject. Using <tt>git format-patch -X --cover-letter -o patches</tt>, where <tt>-X</tt> is the number of patches from HEAD or other commit identifier and <tt>-o</tt> specifies the output directory, will do all of this automatically. A cover letter file with subject of <tt>PATCH [0/X]</tt> where <tt>X</tt> is the total number of patches in the series, will be generated. You can then edit this file with a general top-level subject and give a detailed explanation of the patch series.
+*When sending a series of patches, the patches should be sequence numbered in the subject. Using <tt>git format-patch -X --cover-letter -o patches</tt>, where <tt>-X</tt> is the number of patches from HEAD or other commit identifier and <tt>-o</tt> specifies the output directory, will do all of this automatically. A cover letter file with subject of <tt>PATCH [0/X]</tt> where <tt>X</tt> is the total number of patches in the series, will be generated. You can then edit this file with a general top-level subject and give a detailed explanation of the patch series.
 *It is nice if the subject includes mention of the subsystem which it affects like the following:<p><code>[PATCH 2/5] ext2: improve scalability of bitmap searching</code></p>
 *Various patch scripts used by developers will strip away any text inside brackets []. You should place information which has no long-term relevance to the patch inside them. This includes the word <code>PATCH</code> and any sequence numbering. The subsystem identifier <code>ext2</code> should hence be outside brackets.

@@ Line 26: / Line 26: @@
 *Add a Signed-off-by: line with your name and email address. If you are the person responsible for submitting patches for your group or company, you may have multiple Signed-off-by lines.
-== The diff ==
+== Generating the Patches ==
+All patches should be generated using the <code>git format-patch</code> command. No exceptions.
-* Patches should be in `patch -p1' form:
-  --- a/kernel/sched.c
-  +++ b/kernel/sched.c
-* Make sure that your patches apply to the latest version of the kernel tree from CVS on linux-mips.org.  I'll work out any rejects/incompatibilities.  There are of course exceptions to this.
-*Ensure that your patch does not add new trailing whitespace.  The below script will fix up your patch by stripping off such whitespace.
-<pre>
-#!/bin/sh
-−
-strip1()
-−
-	TMP=$(mktemp /tmp/XXXXXX)
-	cp $1 $TMP
-	sed -e '/^+/s/[ 	]*$//' < $TMP > $1
-	rm $TMP
-−
-−
-for i in $*
-do
-	strip1 $i
-done</pre>
 == Overall ==

@@ Line 15: / Line 15: @@
 == Changelog ==
-* Bear in mind that the Subject: and changelog which you provide will propagate all the way into the permanent kernel record.  Other developers will want to read and understand your patch and changelog years in the future. So the changelog should describe the patch fully:
+Bear in mind that the changelog will also propagate all the way to Linus' tree. The changelog must describe the patch fully.
-:* why the kernel needed patching
+*Here are some guidelines for changelog content:
-:* the overall design approach in the patch
+**Why the kernel needed patching.
-:* implementation details
+**What the overall design approach in the patch was.
-:* testing results
+**Implementation details.
-* Don't bother mentioning what version of the kernel the patch applies to ("applies to 2.6.8-rc1").  This is not interesting information - once the patch is in bitkeeper, of _course_ it applied, and it'll probably be merged into a later kernel than the one which you wrote it for.
+**Any testing results.
-* Do not refer to earlier patches when changelogging a new version of a patch.  It's not very useful to have a bitkeeper changelog which says "OK, this fixes the things you mentioned yesterday".  Each iteration of the patch should contain a standalone changelog.  This implies that you need a patch management system which maintains changelogs.  See below.
-* Add a Signed-off-by: line.
-* Most people's patch receiving scripts will treat a ^--- string as the separator between the changelog and the patch itself.  You can use this to ensure that any diffstat information is discarded when the patch is applied:
-<pre>
+*There is no point in mentioning what version of the kernel the patch applies to. This is not interesting information as once the patch is in git, it will probably be merged into a later kernel version than the one which you wrote it for anyway.
-	Another few #if/#ifdef cleanups, this time for the PPC architecture.
+*Do not refer to earlier patches in the changelog of a new version of a patch. It is not very useful to have a git changelog which says "OK, this fixes the things you mentioned yesterday". Each iteration of the patch should contain a standalone changelog.
+*Add a Signed-off-by: line with your name and email address. If you are the person responsible for submitting patches for your group or company, you may have multiple Signed-off-by lines.
-	Signed-off-by: <valdis.kletnieks@vt.edu>
-	Signed-off-by: Andrew Morton <akpm@osdl.org>
-	---
-−
--akpm/arch/ppc/kernel/process.c                    |    2 +-
--akpm/arch/ppc/platforms/85xx/mpc85xx_cds_common.c |    2 +-
--akpm/arch/ppc/syslib/ppc85xx_setup.c              |    4 ++--
-files changed, 4 insertions(+), 4 deletions(-)
-−
-	--- 25/arch/ppc/kernel/process.c
-	+++ 25/arch/ppc/kernel/process.c
-	@@ -667,7 +667,7 @@ void show_stack(struct task_struct *tsk,
-</pre>
 == The diff ==