All patches must include base-commit info
If Greg KH ever writes a book about his work as the stable kernel maintainer, it should be titled “Everyone must upgrade” (or it could be a Dr. Who fanfic about Cybermen, I guess). Today, I'm going to borrow a leaf out of that non-existent book to loudly proclaim that all patch submissions must include base-commit info.
What is a base-commit?
When you submit a single patch or a series of patches to a kernel maintainer, there is one important piece of information that they need to know in order to properly apply it. Specifically, they need to know what was the state of your git tree at the time when you wrote that code. Kernel development moves very quickly and there is no guarantee that a patch written mid-January would still apply at the beginning of February, unless there were no significant changes to any of the files your patch touches.
To solve this problem, you can include a small one-liner in your patch:
This tells the person reviewing your patch that, at the time when you wrote your code, the latest commit in the git repository was
abcde12345. It is now easy for the maintainer to do the following:
git checkout -b incoming_patch abcde12345 git am incoming_patch.mbx
This will tell git to create a new branch using
abcde12345 as the parent commit and apply your patches at that point in history, ensuring that there will be no failed or rejected hunks due to recent code changes.
After reviewing your submission the maintainer can then merge that branch back into master, resolving any conflicts during the merge stage (they are really good at that), instead of having to modify patches during the
git am stage. This saves maintainers a lot of work, because if your patches require revisions before they can be accepted, they don't have to manually edit anything at all.
Automated CI systems
base-commit info really makes a difference when automated CI systems are involved. With more and more CI tests written for the Linux kernel, maintainers are hoping to be able to receive test reports for submitted patches even before they look at them, as a way to save time and effort.
Unfortunately, if the CI system does not have the
base-commit information to work with, it will most likely try to apply your patches to the latest master. If that fails, there will be no CI report, which means the maintainers will be that much less likely to look at your patches.
How to add
base-commit to your submission
If you are using
git-format-patch (and you really should be), then you can already automatically include the base commit information. The easiest way to do so is by using topical branches and
git format-patch --base=auto, for example:
$ git checkout -t -b my-topical-branch master Branch 'my-topical-branch' set up to track local branch 'master'. Switched to a new branch 'my-topical-branch' [perform your edits and commits] $ git format-patch --base=auto --cover-letter -o outgoing/ master outgoing/0000-cover-letter.patch outgoing/0001-First-Commit.patch outgoing/...
When you open
outgoing/0000-cover-letter.patch for editing, you will notice that it will have the
base-commit: trailer at the very bottom.
Once you have the set of patches to send, you should run them through
checkpatch.pl to make sure that there are no glaring errors, and then submit them to the proper developers and mailing lists.
You can learn more by reading the submitting patches document, which now includes a section about
base-commit info as well.