Difference between revisions of "Submitting Patches"

From LinuxMIPS
Jump to: navigation, search
m (moved The perfect patch to Submitting Patches: The information presented here is very old and CVS specific.)
(Delivery)
Line 2: Line 2:
  
 
== Delivery ==
 
== Delivery ==
 
+
Patches are submitted via email only. Please read [[Mailing-patches]] for instructions once you have completed your code changes.
* Patches are delivered via email only. Downloading them from internet servers is a pain.
+
* Don't compress patches.  Compressing means the receiving side has to uncompress them adding more work.
+
* Just patches.  No tarballs or other "kernel construction kits".
+
* One patch per email, with the changelog in the body of the email.
+
  
 
== Subject ==
 
== Subject ==

Revision as of 18:29, 6 September 2012

This article is meant to help people to describe how to create, maintain and send patches that are easy to handle for the kernel maintainer.

Delivery

Patches are submitted via email only. Please read Mailing-patches for instructions once you have completed your code changes.

Subject

  • The email's Subject: should concisely describe the patch which that email contains. The Subject: should not be a filename. Do not use the same Subject: for every patch in a whole patch series.

    Bear in mind that the Subject: of your email becomes a globally-unique identifier for that patch. It propagates all the way into BitKeeper. The Subject: may later be used in developer discussions which refer to the patch. People will want to google for the patch's Subject: to read discussion regarding that patch.

  • When sending a series of patches, the patches should be sequence-numbered in the Subject:
  • It is nice if the Subject: includes mention of the subsystem which it affects. See example below.
  • Example Subject:
    [patch 2/5] ext2: improve scalability of bitmap searching
  • Note that various people's patch receiving scripts will strip away Subject: text which is inside brackets []. So you should place information which has no long-term relevance to the patch inside brackets. This includes the word "patch" and any sequence numbering. The subsystem identifier ("ext2:") should hence be outside brackets.

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:
  • why the kernel needed patching
  • the overall design approach in the patch
  • implementation details
  • testing results
  • 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.
  • 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:
	Another few #if/#ifdef cleanups, this time for the PPC architecture.

	Signed-off-by: <valdis.kletnieks@vt.edu>
	Signed-off-by: Andrew Morton <akpm@osdl.org>
	---

	 25-akpm/arch/ppc/kernel/process.c                    |    2 +-
	 25-akpm/arch/ppc/platforms/85xx/mpc85xx_cds_common.c |    2 +-
	 25-akpm/arch/ppc/syslib/ppc85xx_setup.c              |    4 ++--
	 3 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,

The diff

  • 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.
#!/bin/sh
 
strip1()
{
	TMP=$(mktemp /tmp/XXXXXX)
	cp $1 $TMP
	sed -e '/^+/s/[ 	]*$//' < $TMP > $1
	rm $TMP
}
 
for i in $*
do
	strip1 $i
done

Overall

  • 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 for some hints.
  • Mail yourself a decent-sized patch and check that it still applies.

Credits

This article is derived from Andrew Morton's article at http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt.

Tools