• Immutable Page
  • Info
  • Attachments

PatchSeries

You have found something that you would like to work on. If not, see start kernel hacking.

Creating Patches

A patch is commonly created from a single commit when development is done using git. When you commit code using git that you intend to contribute to the kernel you must use a specific format for the git changelog message. See how to write a changelog.

Patches can be created in a variety of ways. One method, when using git is to create a patch from the last commit:

git format-patch HEAD~

Patch vs Patch Series

A patch should do one thing and one thing only. This aids review and helps find where bugs were introduced. If you have more than one thing that you would like to do you need to craft a patch series.

Patch Series

A patch series is a series of commits that are linked together when being submitted (by email to the appropriate kernel mailing list). A patch series often includes a cover letter as the first patch (patch number 0). A patch series may be created from a set of git commits using the following command, where N is the number of commits to include.

git format-patch -N -o path/to/dir --cover-letter

You must then manually edit the cover letter, more on this below.

You should go through your patch series, either view each patch in an editor or you may use

git log --color=always --patch --reverse $HASH.. | less

making sure that each patch is correct. Make sure no changes accidentally slipped into the wrong commit. You also need to make sure that the patch contains no glaring errors. If code displayed in the patch has issues (even if the patch does not change that code) then it will likely not pass review. This can be a little difficult when crafting patches that do one thing and one thing only. Crafting patches is one of the core activities in contributing code to the kernel, it takes practice and thought.

Cover Letter

You may like to include a cover letter with your patch series. This is where you describe why the series has been created, what it fixes, and briefly what each patch in the series does. Examples can be found on LKML, here is an example by Paul E. McKenny and another by Roy Pledge. If you are writing driver code and you have not tested the code on real hardware you may like to add a line stating so in the cover letter. You should also follow all guidelines in the kernel documentation on submitting patches.

Sending Patch Series

Once you are happy with your patch series you can send it using git. You may wish to use scripts/get_maintainer.pl to find out who to send the series to. If you fill in the email headers within the cover letter (To and Cc) then you may send your series using the command

git send-email --to-cover --cc-cover path/to/patch/dir/*.patch

Check the output from this command to make sure you are not including anything unusual (editor autosave files etc). Also you can check that you formatted the header addresses correctly if you chose to follow the above method.

You may like to do a test run sending the patch series to yourself to verify that all is correct.

See also first kernel patch, git tips and patch tips and tricks.

Tell others about this page:

last edited 2017-04-18 02:36:15 by Tobin Harding