This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
en:developers:documentation:submittingpatches [2016/08/01 09:50] Kalle Valo [Subject name] Fix three dashes |
en:developers:documentation:submittingpatches [2019/11/27 15:44] Kalle Valo [Who to address] add link to ath11k |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | |||
Line 29: | Line 28: | ||
Cc: Driver maintainers, Other Developers</code> | Cc: Driver maintainers, Other Developers</code> | ||
- | Where [[en/developers/maintainers|Maintainers]] contains the list of maintainers for the piece of code you are patching. //Other Developers// in this case can be a list of developers who you think may like to review this patch or who changed the code you are working on recently. | + | Where [[en/developers/maintainers|Maintainers]] contains the list of maintainers and mailing lists for the piece of code you are patching. //Other Developers// in this case can be a list of developers (or mailing lists) who you think may like to review this patch or who changed the code you are working on recently. |
- | ===== Subject name ===== | + | Do note that drivers might have special requirements, the best is to check them from the corresponding wiki page. Here's a list for few of them: |
+ | |||
+ | * [[en/users/drivers/ath10k/submittingpatches|ath10k]] | ||
+ | * [[en/users/drivers/ath11k/submittingpatches|ath11k]] | ||
+ | ===== Checking state of patches from patchwork ===== | ||
+ | |||
+ | All wireless patches are tracked in [[https://patchwork.kernel.org/project/linux-wireless/list/|linux-wireless patchwork project]]. From patchwork you can check the state of the patch and to whom it is assigned. Here's a quick link to see all the patches, no matter what's the state: | ||
+ | |||
+ | [[https://patchwork.kernel.org/project/linux-wireless/list/?state=*]] | ||
+ | |||
+ | Always avoid contacting maintainers directly, they get way too much email already. Instead use the link above to find your patch and see the status. Only in last resort contact the maintainers, and do that by replying to your own patch and ask for status. Do not top post! | ||
+ | |||
+ | Different patchwork states and their meanings: | ||
+ | |||
+ | * **New**: No action haven't taken yet, expect maybe assigned to a correct maintainer. | ||
+ | * **Under Review**: The maintainer is waiting review comments from others. | ||
+ | * **Accepted**: The maintainer has applied the patch to his/her tree. | ||
+ | * **Rejected**: The maintainer rejected the patch, reasons stated in an email. | ||
+ | * **Changes Requested**: Either the maintainer or a reviewer requested changes in the patch. The maintainer expects the patch author to submit a new version. | ||
+ | * **Deferred**: The maintainer has postponed the review of the patch for some reason, for example due to lack of time, patch being to controversial or something else. Patch author doesn't need to take any action, the maintainer will revisit the patch in a later time. | ||
+ | * **Awaiting Upstream**: The patch depends on an another patch from a different tree, for example a wireless driver needing a specific mac80211 patch to implement a new feature. | ||
+ | * **RFC**: The patch is sent as Request For Comments. The maintainer expects the patch author to submit a new version. | ||
+ | * **Superseded**: There's a new version of the patch available, the maintainer has skipped this version. | ||
+ | * **Not Applicable**: The patch is either not part of wireless subsystem or it will be applied via different trees (for example net-next or driver maintainer trees). The patch is considered as dropped from now on and needs to be resubmitted for the maintainer to reconsider it. | ||
+ | |||
+ | ===== Subject ===== | ||
If what you are sending is a patch you can use a subject as follows: | If what you are sending is a patch you can use a subject as follows: | ||
Line 70: | Line 94: | ||
If a patch in a bigger patchset changes resubmit the whole patchset, even the patches which have not changes. The maintainers look at patchsets as a complete unit, usually they do not want to take patches individually from a patchset. | If a patch in a bigger patchset changes resubmit the whole patchset, even the patches which have not changes. The maintainers look at patchsets as a complete unit, usually they do not want to take patches individually from a patchset. | ||
+ | |||
+ | ===== Tree labels ===== | ||
+ | |||
+ | Labeling patches with what tree the patch should go to helps maintainers to prioritise and sort patches and avoids unnecessary emails, which saves everyone time and speeds up patch review. Here are some tips how to label wireless patches. | ||
+ | |||
+ | If you want to target your patch to a specific release (for example that the patch should go -rc release not -next) you can inform the maintainer by adding the release number inside the PATCH brackets: | ||
+ | |||
+ | <code>[PATCH 4.20] subsystem: fix foo</code> | ||
+ | |||
+ | If you want to make it clear to the maintainer that the patch should NOT go to -rc release but to -next instead you can add "-next" to PATCH brackets: | ||
+ | |||
+ | <code>[PATCH -next] subsystem: fix foo</code> | ||
+ | |||
+ | Alternatively you can specify the exact tree you are targetting by adding the name of the git tree inside PATCH brackets: | ||
+ | |||
+ | <code>[PATCH mac80211] mac80211: fix foo | ||
+ | [PATCH mac80211-next] mac80211: implement very-cool-feature | ||
+ | [PATCH wireless-drivers] ath10k: fix foo | ||
+ | [PATCH wireless-drivers-next] ath10k: implement awesome-feature | ||
+ | </code> | ||
+ | |||
===== Sending large patches or multiple patches ===== | ===== Sending large patches or multiple patches ===== | ||
Line 84: | Line 129: | ||
[PATCH 4/4] driver_name: optimize bar at init time</code> | [PATCH 4/4] driver_name: optimize bar at init time</code> | ||
On the e-mail with subject, "[PATCH 0/4] driver_name: introduce foo and bar", you would give a brief overview of all the changes. No patch should be included in that e-mail, and as that e-mail will not end up in the change logs it should not contain anything that should be archived, only a rough overview over the purpose of the patch set, no in-depth description which should be in the changelog for each patch. | On the e-mail with subject, "[PATCH 0/4] driver_name: introduce foo and bar", you would give a brief overview of all the changes. No patch should be included in that e-mail, and as that e-mail will not end up in the change logs it should not contain anything that should be archived, only a rough overview over the purpose of the patch set, no in-depth description which should be in the changelog for each patch. | ||
+ | |||
===== Format of patches ===== | ===== Format of patches ===== | ||
- | We prefer patches to be inline-text at the end of the body of the e-mail. You can use git-diff or the like to generate the patch. Additionally note that we prefer to apply patches with -p1. A header as follows is then acceptable: | + | We prefer patches to be inline-text at the end of the body of the e-mail. It's strongly recommended to use git-format-patch and git-send-email tools to submit patches as they use the correct format automatically. Additionally note that we prefer to apply patches with git-am (using the -p1 diff format). A header as follows is then acceptable: |
Line 107: | Line 153: | ||
include/net/ieee80211_regdomains.h | 196 ++++++++ | include/net/ieee80211_regdomains.h | 196 ++++++++ | ||
...</code> | ...</code> | ||
- | Please also read the [[https://kernel.org/doc/Documentation/SubmittingPatches|official Linux SubmittingPatches]] documentation, especially Section 12 and the **Developer's Certificate of Origin**. Do not submit patches unless you have read, understood and agreed to the certificate. | + | Please also read the [[https://www.kernel.org/doc/html/latest/process/submitting-patches.html|official Linux SubmittingPatches]] documentation, especially the **[[https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin|Developer's Certificate of Origin]]**. Do not submit patches unless you have read, understood and agreed to the certificate. |
Line 190: | Line 236: | ||
... ETC ...</code> | ... ETC ...</code> | ||
- | ===== More patch work references ===== | + | ===== Frequent problems in patch submissions ===== |
+ | |||
+ | ==== Patch version missing ==== | ||
+ | |||
+ | If you send a new version of the patch or patchset you should always add a version number. The first version does not need to be shown but starting from second version the version number must be available: | ||
+ | |||
+ | [PATCH] ath10k: fix DMA allocation | ||
+ | [PATCH v2] ath10k: fix DMA allocation | ||
+ | [PATCH v3] ath10k: fix DMA allocation | ||
+ | ... | ||
+ | [PATCH v11] ath10k: fix DMA allocation | ||
+ | |||
+ | You can add the version with switch ''--subject-prefix'': | ||
+ | |||
+ | git format-patch --subject-prefix="PATCH v2" | ||
+ | |||
+ | ==== Changelog missing ==== | ||
+ | |||
+ | When sending a new version of a patch or patchset you should **always** add a changelog so that maintainer can easily see what has changed. | ||
+ | |||
+ | If you have just one patch you can add the changelog after the ''%%---%%'' (three dashes) line. | ||
+ | |||
+ | If you have multiples patches (called a patchset) add the changelog to the cover letter. You can create the cover letter with the switch ''--cover-letter'': | ||
+ | |||
+ | git format-patch --subject-prefix="PATCH v2" --cover-letter | ||
+ | |||
+ | ==== Signed-off-by missing ==== | ||
+ | |||
+ | Read [[https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin|Developer's Certificate of Origin]] and add Signed-off-by to the commit log. | ||
+ | |||
+ | ==== Format issues ==== | ||
+ | |||
+ | Patch is somehow whitespace damaged, for example tabs converted to spaces, extra new lines or other modifications which prevent applying the patch without manual fixing. Or the mail is in HTML format which most of the mailing lists even block silently. | ||
+ | |||
+ | The best way to avoid all formatting issues is to use [[https://www.kernel.org/pub/software/scm/git/docs/git-send-email.html|git send-email]]. See [[en/developers/Documentation/git-guide|linux-wireless git guide]] for more information. | ||
+ | |||
+ | ==== Fixes line is incorrect ==== | ||
+ | |||
+ | The correct format for the commit references in Fixes line is the 12 initial digits | ||
+ | of the SHA1_ID of the commit, followed by a space, followed by the | ||
+ | commit log message header line text enclosed in parentheses and | ||
+ | double quotes with no line breaks whatsoever. | ||
+ | The fixes lines must be placed just above the signed-off-by lines. | ||
+ | |||
+ | Example: | ||
+ | |||
+ | Fixes: c742e623e941 ("mwifiex: sdio card reset enhancement") | ||
+ | |||
+ | ==== Commit reference is wrong ==== | ||
+ | |||
+ | The correct format for the commit references in commit logs is to start with the string "commit", followed by a space, followed 12 initial digits | ||
+ | of the SHA1_ID of the commit, followed by a space and followed by the | ||
+ | commit log message header line text enclosed in parentheses. | ||
+ | |||
+ | Example: | ||
+ | |||
+ | <code> | ||
+ | commit f99a6abe59e096cc2c753e667c19f22022e3bef4 | ||
+ | Author: Sara Sharon <sara.sharon@intel.com> | ||
+ | Date: Sun Mar 5 18:35:02 2017 +0200 | ||
+ | |||
+ | iwlwifi: mvm: memset binding before setting values | ||
+ | |||
+ | The changes in commit 9415af7f306b ("iwlwifi: mvm: support new binding | ||
+ | API") assigned values that were later memset to 0. Move the memset | ||
+ | earlier. | ||
+ | |||
+ | Fixes: 9415af7f306b ("iwlwifi: mvm: support new binding API") | ||
+ | Signed-off-by: Sara Sharon <sara.sharon@intel.com> | ||
+ | Signed-off-by: Luca Coelho <luciano.coelho@intel.com> | ||
+ | </code> | ||
+ | |||
+ | ==== Commit title is wrong ==== | ||
+ | |||
+ | The correc tformat for the commit title is name of driver, followed by a colon, followed by a space and then followed by the actual title. You can use ''git log'' to check older commits and see what prefix was used: | ||
+ | |||
+ | <code> | ||
+ | $ git log --oneline --follow --no-merges -20 drivers/net/wireless/marvell/mwifiex/11ac.c | ||
+ | 277b024e5e3d mwifiex: move under marvell vendor directory | ||
+ | 65da33f5557f mwifiex: update Copyright to 2014 | ||
+ | cf831ffe4473 mwifiex: fix IE parsing issues | ||
+ | d51246481c7f mwifiex: save and copy AP's VHT capability info correctly | ||
+ | 5f6d5983394f mwifiex: add VHT support for TDLS | ||
+ | 9ed230bcbab7 mwifiex: pass ieee80211_vht_cap to mwifiex_fill_vht_cap_tlv | ||
+ | 406d702b47a2 mwifiex: improve readability in 11ac mcsmap to maxrate conversion | ||
+ | 89467d8ca21b mwifiex: make 11ac mcs rate tables global and const | ||
+ | 7abf4129e6df mwifiex: make use of IEEE80211_VHT_MCS_NOT_SUPPORTED | ||
+ | 0648f3a4b0e9 mwifiex: correct bss_mode check while appending vht operation IE | ||
+ | 2b6254dacfe6 mwifiex: use separate AMPDU tx/rx window sizes in 11ac networks | ||
+ | 83c78da983d6 mwifiex: add support to configure VHT for AP mode | ||
+ | a5f390562a37 mwifiex: add 802.11AC support | ||
+ | </code> | ||
+ | |||
+ | ==== Too many patches ==== | ||
+ | |||
+ | The recommend size is 10-12 patches per patchset. More than that it gets difficult for reviewers and maintainers. Of course there's no hard rule, for simple patches more than that might be ok but then again for more complex patches even 10 patches per patchset might be too much. | ||
+ | |||
+ | ==== Resubmit the whole patchset ===== | ||
+ | |||
+ | Even if just one patch has changed in a patch series resubmit the whole patchset (and remember to increase the version number), do not just resubmit that one changed patch. The reason is that it's difficult to apply patches in correct order when some of them are submitted separately. | ||
+ | |||
+ | ==== Commit log does not answer "Why?" ==== | ||
+ | |||
+ | The commit log should //always// answer the question "Why?" and describe the reason what | ||
+ | motivated to implement the patch. This is the most important part of the commit log as this helps maintainers, backports, distros etc to make decisions if the patch is important for them or not and to what release it should go. | ||
+ | |||
+ | The commit log needs to tell why you wrote the patch. If you fixed a bug give a short summary of the bug (can be a long one as well, of course) from user's point of view, and if there's a publically available bug report include a link to that. If you are fixing a warning from a compiler or a static checker add the warning from tool. Or if it's just code cleanup or fixing a theoretical issue, and does not have practical user visible changes, mention that also. | ||
+ | |||
+ | ==== Do not top post and edit your quotes ==== | ||
+ | |||
+ | Top posting makes following email threads hard to follow and also it makes use of patchwork more difficult, which gets the maintainers grumpy as you are making their work more difficult. So do not top post and instead edit your quotes properly. | ||
+ | |||
+ | <code>A: Because it messes up the order in which people normally read text. | ||
+ | Q: Why is top-posting such a bad thing? | ||
+ | A: Top-posting. | ||
+ | Q: What is the most annoying thing in e-mail? | ||
+ | |||
+ | A: No. | ||
+ | Q: Should I include quotations after my reply? | ||
+ | </code> | ||
+ | |||
+ | More info: http://www.idallen.com/topposting.html | ||
+ | |||
+ | ==== Use RFC or RFT for patches not ready ==== | ||
+ | |||
+ | If the patches are not yet ready to be applied by the maintainer, mark them as RFC (Request For Comments) or RFT (Request For Test). This way the maintainer can easily see that the patch should not be applied yet. This saves a lot of maintainer's time. | ||
+ | |||
+ | |||
+ | ===== More references ===== | ||
Here is a list of links to help you write better patches | Here is a list of links to help you write better patches | ||
- | * [[https://www.kernel.org/doc/Documentation/SubmittingPatches|SubmittingPatches]] | + | * [[https://www.kernel.org/doc/html/latest/process/submitting-patches.html|SubmittingPatches]] |
* https://kernelnewbies.org/FirstKernelPatch | * https://kernelnewbies.org/FirstKernelPatch | ||
* [[http://linux.yyz.us/patch-format.html|http://linux.yyz.us/patch-format.html]] | * [[http://linux.yyz.us/patch-format.html|http://linux.yyz.us/patch-format.html]] | ||
- | * [[http://userweb.kernel.org/~akpm/stuff/tpp.txt|Andrew Morton's ''The perfect patch'']] | + | * [[https://www.ozlabs.org/~akpm/stuff/tpp.txt|Andrew Morton's ''The perfect patch'']] |
+ | * [[http://lkml.kernel.org/r/20171026223701.GA25649@bhelgaas-glaptop.roam.corp.google.com|Make Bjorn's life easier (and grease the path of your patch)]] |