Submitting Patches
Contents
Submitting Patches (to various upstream projects)
Linux
The Linux kernel traditionally uses the "git send-email" workflow for patch submission, once you have some commits you want included, you email them as git "patches" to the mailing list and any relevant maintainers.
This can be a bit of a daunting task, there are many guides out there explaining how to do this, but they usually miss bits out or do a poor job of explaining how git send-email
actually works.
Configuring git send-email
This is pretty well documented elsewhere, notably in the freedesktop pulseaudio docs and here: https://burzalodowa.wordpress.com/2013/10/05/how-to-send-patches-with-git-send-email/
To send patches from GMail, create an app password on https://myaccount.google.com/apppasswords .
Example config for GMail:
$ cat ~/.gitconfig [sendemail] smtpEncryption = tls smtpServer = smtp.gmail.com smtpUser = username@gmail.com smtpServerPort = 587 confirm = always
Sending patches
This is the process I Caleb use, it's by no means perfect, I'd suggest you take it and modify it to suite your needs.
Once you have your commit(s) ready, format them as patches so we can run them through checkpatch and get_maintainer:
$ git log --oneline # note down the hash of the first commit in your series, e.g: 9f0cfbc330a2 arm64: dts: qcom: sdm845-oneplus-common: add nodes for q6voice apr service aa209f22271d arm64: dts: xiaomi-beryllium-common: Add nodes for q6voice apr service 0fe8a293245b arm64: dts: qcom: sdm845: Add q6voice APR service device nodes # <-- this is the first commit
Now generate a bunch of .patch files using git format-patch
$ git format-patch 0fe8a293245b^ # <-- the caret '^' tells git to include the referenced commit, without it only the top 2 commits would be used 0001-arm64-dts-qcom-sdm845-Add-q6voice-APR-service-device.patch 0002-arm64-dts-xiaomi-beryllium-common-Add-nodes-for-q6vo.patch 0003-arm64-dts-qcom-sdm845-oneplus-common-add-nodes-for-q.patch
You can also use relative commit reference instead of full commit SHA, like git format-patch HEAD~3
to generate patches for 3 last commits. This way you don't need to know the exact hashes of commits.
We can now run checkpatch to make sure our patches pass the checks, if you forget this maintainers will point it out and have you re-do it.
$ ./scripts/checkpatch.pl *.patch
If you have errors, fix them, create a fixup commit for whichever patch(es) you had to fix (e.g. git commit --fixup aa209f22271d
) and then squash the series again with git rebase -i 0fe8a293245b^
, and start again from the top of this section.
Once checkpatch is happy, you can use get_maintainer.pl to find a list of emails to send your patch to, I have a handy bash function for this which formats the output so it can be directly appended to git send-email
, you might want to add it to your .bashrc or wherever else...
gencclist () { echo "$(./scripts/get_maintainer.pl --nogit --nogit-fallback --norolestats --r "$@" | xargs -I {} echo --to=\"{}\" | tr '\n' ' ')" }
Now we can simply run:
$ gencclist *.patch --to="Some Maintainer <someone@kernel.org>" --to="linux-arm-msm@vger.kernel.org" --to="devicetree@vger.kernel.org" --to="linux-kernel@vger.kernel.org"
Finally, we're ready to send our patches, it's worth noting that the .patch files we generated are not used for this, instead git send-email produces the patches directly, it will format them properly for the kernel, including the patch version if necessary.
$ git send-email 0fe8a293245b^ --to="Some Maintainer <someone@kernel.org>" --to="linux-arm-msm@vger.kernel.org" --to="devicetree@vger.kernel.org" --to="linux-kernel@vger.kernel.org" /tmp/EvaxiVuPLX/0001-arm64-dts-qcom-sdm845-Add-q6voice-APR-service-device.patch /tmp/EvaxiVuPLX/0002-arm64-dts-xiaomi-beryllium-common-Add-nodes-for-q6vo.patch /tmp/EvaxiVuPLX/0003-arm64-dts-qcom-sdm845-oneplus-common-add-nodes-for-q.patch
Or git send-email <...params...> *.patch
You can also use git send-email --to-cmd=./scripts/get_maintainer.pl ..
to automatically use its results in --to
arguments.
If you're sending a series and would like to include a cover letter, add the --annotate --cover-letter
arguments to git send-email. This will automatically generate a shortlog and a diffstat for the series. I'd recommend writing your cover letter separately and pasting it in to avoid potentially losing data.
Dont forget to add --cc="~postmarketos/upstreaming@lists.sr.ht"
and --cc="phone-devel@vger.kernel.org"
for phone related patches.
To send a new version of your patches (e.g. a version 2), add -v2
. This works for all versions (e.g. -v5
).
See also
- https://www.kernel.org/doc/Documentation/devicetree/bindings/submitting-patches.txt
- A more thorough guide on setting up git send-email: https://git-send-email.io/