Submitting Patches

From postmarketOS
Jump to navigation Jump to search

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