So now you have a perfect series of patches for posting, but the work is not done quite yet. Each patch needs to be formatted into a message which quickly and clearly communicates its purpose to the rest of the world. To that end, each patch will be composed of the following:
- An optional „From“ line naming the author of the patch. This line is only necessary if you are passing on somebody else’s patch via email, but it never hurts to add it when in doubt.
- A one-line description of what the patch does. This message should be enough for a reader who sees it with no other context to figure out the scope of the patch; it is the line that will show up in the „short form“ changelogs. This message is usually formatted with the relevant subsystem name first, followed by the purpose of the patch. For example:gpio: fix build on CONFIG_GPIO_SYSFS=n
- A blank line followed by a detailed description of the contents of the patch. This description can be as long as is required; it should say what the patch does and why it should be applied to the kernel.
- One or more tag lines, with, at a minimum, one Signed-off-by: line from the author of the patch. Tags will be described in more detail below.
The above three items should, normally, be the text used when committing the change to a revision control system. They are followed by:
- The patch itself, in the unified („-u“) patch format. Using the „-p“ option to diff will associate function names with changes, making the resulting patch easier for others to read.
You should avoid including changes to irrelevant files (those generated by the build process, for example, or editor backup files) in the patch. The file „dontdiff“ in the Documentation directory can help in this regard; pass it to diff with the „-X“ option.
The tags mentioned above are used to describe how various developers have been associated with the development of this patch. They are described in detail in the SubmittingPatches document; what follows here is a brief summary. Each of these lines has the format:
tag: Full Name <email address> optional-other-stuff
The tags in common use are:
- Signed-off-by: this is a developer’s certification that he or she has the right to submit the patch for inclusion into the kernel. It is an agreement to the Developer’s Certificate of Origin, the full text of which can be found in Documentation/SubmittingPatches. Code without a proper signoff cannot be merged into the mainline.
- Acked-by: indicates an agreement by another developer (often a maintainer of the relevant code) that the patch is appropriate for inclusion into the kernel.
- Tested-by: states that the named person has tested the patch and found it to work.
- Reviewed-by: the named developer has reviewed the patch for correctness; see the reviewer’s statement in Documentation/SubmittingPatches for more detail.
- Reported-by: names a user who reported a problem which is fixed by this patch; this tag is used to give credit to the (often underappreciated) people who test our code and let us know when things do not work correctly.
- Cc: the named person received a copy of the patch and had the opportunity to comment on it.
Be careful in the addition of tags to your patches: only Cc: is appropriate for addition without the explicit permission of the person named.