Debian BTS #1032074.
Code in Perl's MySQL DBD: mysql_get_client_version() user.
MariaDB discussion: Revert inappropriate libmariadb stable ABI version changes.

October 11, 2009 updates are marked in Blue.

What is the patch system?

Please note that patches for other trees (eg, -rmk-pxa) should be submitted to the appropriate person and not this patch system.

Also note that this patch system no longer accepts patches for the 2.4 series kernels. Such patches should be submitted to Vincent Sanders, as per the announcement on the linux-arm-kernel mailing list.

However, this does not give the full story of patches applied; changes that go into Linus kernels are outside the scope of this patch system.

There are certain restrictions on the system, so please follow these instructions carefully.

Which patches should be submitted?

• Evaluation boards/platforms. (eg, EBSA285, Intel Assabet, ARM Integrator, etc)
• Popular platforms. (eg, iPAQ)
• Suitably generic device drivers and features. (eg, ARM primecells, MMC core drivers, etc)
• Bug fixes to existing code already in the -rmk tree.

Once the 2.7 kernel opens, support for new features in the 2.6 kernels will not be accepted unless similar support is also available for the 2.7 kernel. This is to encourage feature development in the correct place - in the development kernels. These features can be appropriately merged upstream, and then reviewed by the wider Linux community. They can also be back-ported using the back-compatibility features to the stable kernel series, upon which products would be based.

This policy is consistent with the philosophy of the wider Linux community; back-porting features from a development to a stable kernel is acceptable, where as forward-porting is not, especially when the same code base is maintained on both kernel series.

Legal Copyright Issues

This means that the licensing of the source code must be compatible with the GNU General Public License version 2. It is generally a good idea to state your licensing policy at the top of any C, assembler or header file you create. The following is provided as an example only:

/*
 *  linux/arch/arm/kernel/setup.c
 *
 *  Copyright (C) 1995-2004 Russell King
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation.
 */

If you have any doubts about the suitability of your licensing terms, please consult your Copyright Lawyer.

Sending in a patch

1. Generate the patch.
   
   • Patch content.
     The following are good guidelines to follow when thinking about what to include in a patch:
     • It should cover for one feature, one driver, or one bug fix only.
     • If you're changing an existing file in the kernel, it's best to send this change as a separate patch. It is acceptable and you are encouraged to batch up related changes within a subsystem (eg a driver with its associated makefile and config.in/Kconfig changes) into one patch file.
     • If you're submitting the code for a new machine type, it is acceptable to send the arch/arm/mach-* changes in one large patch provided it does not exceed the maximum patch size. If it does, try to split it up logically (eg, separate the include files.)
     • It is most important that any patch, if applied on its own, should not prevent the kernel from building. This generally means that if a patch introduces extra includes to any files, those files should either be supplied with the same patch, or be pre-existing in the kernel.
     • Patches should not include changes to the arch/arm/tools/mach-types file.

     When generating or splitting up a patch, think about the probability of your patch applying to a different (later) kernel version than the one that you generated it against. The higher the probability, the better.

     This is especially important, since various patches are applied to various source trees, which ultimately end up going to different people or places. From time to time, advice appears on the linux-arm-kernel concerning these, but you should not rely on those messages.

   • Options for the diff program.
     Please tell diff to generate unified patches, recursing and new files if necessary. The diff options are -urN. You may also like to use the -p option so that diff includes the C function name that the change is occurring in.
   • Directory names.
     Please note that this is a fundamental requirement for your patch to be accepted.
     • The diff must be generated using a path relative to the directory directly above the main linux/ source tree.
     • Both the old and new directories must contain the same number of slashes (otherwise patch gets confused).
     • If you only want a small area of the kernel, then use (eg) diff -urN linux.orig/arch/arm/kernel linux/arch/arm/kernel.
       

   Here are sample patch headers from a correctly generated patches (note that the line starting "diff" is optional. Also, Additional lines created by cvs diff -u are also acceptable):

   diff -Nru linux.orig/lib/string.c linux/lib/string.c
   --- linux.orig/lib/string.c	Thu Feb 14 09:42:18 2002
   +++ linux/lib/string.c	Thu Feb 14 09:42:18 2002
   

   diff -Nru a/lib/string.c b/lib/string.c
   --- a/lib/string.c	Thu Feb 14 09:42:18 2002
   +++ b/lib/string.c	Thu Feb 14 09:42:18 2002
   

   diff -Nru a/lib/string.c.orig a/lib/string.c
   --- a/lib/string.c.orig	Thu Feb 14 09:42:18 2002
   +++ a/lib/string.c	Thu Feb 14 09:42:18 2002
   

   --- a/lib/string.c.orig	Thu Feb 14 09:42:18 2002
   +++ a/lib/string.c	Thu Feb 14 09:42:18 2002
   

   The following are examples of incorrectly generated patches, which result in the patch being rejected and a request to resubmit:

   diff -Nru 2.4.5-rmk7/linux/drivers/pcmcia/sa1100.h linux/drivers/pcmcia/sa1100.h
   --- 2.4.5-rmk7/linux/drivers/pcmcia/sa1100.h    Thu Jun 21 20:19:33 2001
   +++ linux/drivers/pcmcia/sa1100.h       Fri Jun 22 00:00:20 2001
   

   diff -Nru 2.5.4-rmk1/linux-2.5.4/arch/arm/mm/Makefile linux-2.5.4/arch/arm/mm/Makefile
   --- 2.5.4-rmk1/linux-2.5.4/arch/arm/mm/Makefile Mon Feb 18 21:44:12 2002
   +++ linux-2.5.4/arch/arm/mm/Makefile    Tue Feb 19 13:36:35 2002
   

   diff -Nru linux-2.5.4/arch/arm/mm/proc-xscale.S ../2.4.17/cot/linux/arch/arm/mm/proc-xscale.S
   --- linux-2.5.4/arch/arm/mm/proc-xscale.S       Mon Feb 18 21:44:12 2002
   +++ ../2.4.17/cot/linux/arch/arm/mm/proc-xscale.S       Thu Feb 14 13:19:16 2002
   

2. Give the mail a descriptive subject line.
   This will appear on the web page, in the release notes for the next -rmk version of the kernel, and in Linus' release notes as a summary line.

   Things to avoid:

   • Please omit [PATCH] and other "useful" prefixes.
     These are unnecessary with the patch system (except when following up on a patch, described later).
3. Detailed explanation.
   Include some text in the message explaining what the new feature is, the bug, or why the patch is needed. If the patch relies on some other patch being applied before hand, please supply this information here. Please also bear in mind that the description will appear in the message sent to upstream to Linus, and in the mainline git repository.

   This explanation text should be wrapped around column 68 for consistency and readability sake; these comments are also sent to Linus so Linus himself can understand the reasoning behind the changes.

   Things to avoid:

   • diffstat - The patch system generates this internally as required.
4. Signing off the patch
   At the end of the detailed description, please add the Signed-off-by: lines as a group together, separated from the detailed description by one blank line. For more information about this, and what it means to sign off a patch, please see the file Documentation/SubmittingPatches in the Linux Kernel source code, section 1 subsection 11. Please note that the patch system will hide the email address on the web site, but will include it in the comments when submitted to Linus.
5. Patch separator.
   The patch system now accepts two different forms of terminating the description. Both are described here, please use only one form.
   1. On a blank line "PATCH FOLLOWS" (without the quotes). There must be no space or tab characters before or after these words on this line.
   2. On a blank line "---" (three minus-signs without the quotes). Again, there must be no space or tab characters before or after this symbol.
   The second form conforms closer to the format used by the rest of the kernel community.
6. Kernel version.
   On a separate line, add a tag "KernelVersion: " followed by the kernel version that the patch was generated against. This should be formatted as "KernelVersion: 2.6.0-rmk1"
7. Append your patch.
   Append your patch as plain unwrapped text after this line to the end of the message. Note that the patches must be precisely what diff generates. It is not acceptable for TABs to be converted to spaces, or extra newlines or spaces to be added into the file. If you are unsure about the behaviour of your mailer, send the patch to yourself and examine it.

   The patch system now handles MIME attachments, quoted-printable encoded attachments and base64 attachments. This means you can attach your unified diff patchfile to the message, as long as the previous steps have been followed.

8. Mailing your patch.
   Mail it to patches@armlinux.org.uk and check the reply.

   Please do not copy me your patch; the patch system will tell you if it accepted the patch.

If you wish to follow up on the patch, please use the subject line as the key (it should include the exact string "(Patch #number)", where 'number' is the patch number to which you wish to respond). If you have superseded a previous patch, follow the instructions above to send a new patch but add "(Patch #number)" to the subject. The patch system will create a new entry in the patch system with the same patch number but with the digit after the slash incremented, indicating a new patch version. Use the web interface to set the status of the older version as Superseded.

The correct format for the key is:

• Open parenthesis
• The letter P
• The letter a
• The letter t
• The letter c
• The letter h
• A space character
• The '#' symbol
• The patch number
• Close parenthesis

Please note that the patch system only accepts emails containing properly formatted patches; follow up text articles or replies will not be accepted.

General Advice

1. If you have developed a device driver that uses a major/minor pair, please get it allocated according to the linux/Documentation/devices.txt file. Major/minor numbers are device driver specific, not device specific. Any device driver which re-uses major/minor numbers without an extremely good reason (included along with the patch) do not stand any chance of being accepted.
2. To ease the problems of applying patches, I recommend that you send a patch that adds exactly one feature or bug fix in a single email. Mails containing zero or less, or two or more features stand a greater chance of not being applied if any one part of the patch is not acceptable for some reason.
3. Patches that are inter-dependent should not be sent - these significantly increase the probability of both patches being rejected, unless both get applied at the same time. My recommendation is: don't do it.
4. All patches should be complete, that is applying it should not cause any breakage.
   i.e., adding a new architecture inline function in arch/arm/mach-*/include/mach/ should be done such that all existing architectures will still at the very least compile correctly. If you're not sure how it should be handled on a particular architecture, put in a GCC #warning statement.
5. Please note that as of 2.4.10something, all modules must have an appropriate MODULE_LICENSE() tag in them specifying one of the licenses in include/linux/module.h. It is preferable that they also contain MODULE_AUTHOR() and MODULE_DESCRIPTION().

Patch Status

Incoming

All patches received get automatically placed into this category.

Pending

Patches that are going to appear in the kernel are placed into this category. They should eventually move into the "Applied" category.

Applied

All patches that have been applied to the -rmk kernel are located here.

Superseded

The patch is no longer relevant because the problem has been fixed in a different way, or a newer patch has been submitted which makes this patch redundant.

Rejected or Discarded

Didn't like the patch for some reason.

On-hold

A query against the patch is outstanding. Patches in this category are automatically expired to discarded after 3 months.

Kernel 2.5

The changes in this patch are only suitable for the next development series of the kernel.

Rewrite

The patch touches something that desperately needs a re-write, and makes the situation worse.

Other

Patches that don't fall into the above categories.