Konstantin Ryabitsev

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:

base-commit: abcde12345

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

Adding 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.