en:developers:documentation:submittingpatches
Differences
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 [2018/11/16 08:37] Kalle Valo Add a section about tree labels |
en:developers:documentation:submittingpatches [2021/07/28 15:17] Kalle Valo [New driver] add some guidelines for new driver review |
||
|---|---|---|---|
| Line 33: | Line 33: | ||
| * [[en/users/drivers/ath10k/submittingpatches|ath10k]] | * [[en/users/drivers/ath10k/submittingpatches|ath10k]] | ||
| + | * [[en/users/drivers/ath11k/submittingpatches|ath11k]] | ||
| ===== Checking state of patches from patchwork ===== | ===== Checking state of patches from patchwork ===== | ||
| Line 56: | Line 57: | ||
| ===== Subject ===== | ===== 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 should use a subject as follows: |
| Line 80: | Line 81: | ||
| If your patch is just a proposal you can mark the patch as RFC in the subject: | If your patch is just a proposal you can mark the patch as RFC in the subject: | ||
| - | <code>[RFC] subsystem: a new way to do foo</code> | + | <code>[RFC] subsystem: add a new way to do foo</code> |
| If you need to make changes to the patch add a version number inside the brackets: | If you need to make changes to the patch add a version number inside the brackets: | ||
| Line 93: | 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. | ||
| + | |||
| + | Subject lines, like commit messages (see below) should be written in imperative voice ("fix foo and optimize bar"), not in any other way such as past tense ("fixed foo and optimized bar"). | ||
| + | |||
| + | ===== Commit Messages ===== | ||
| + | |||
| + | Please write commit messages, like mentioned for the subject above, in imperative voice. | ||
| + | |||
| + | Commit messages should describe | ||
| + | * why a change was made, | ||
| + | * how it achieves its stated goal, and, | ||
| + | * if applicable, other considerations such as | ||
| + | * alternatives that were considered, | ||
| + | * implications on other code, | ||
| + | * possible security implications, | ||
| + | * etc. | ||
| + | |||
| + | If you find yourself listing out a number of changes in the commit message as a bulleted list or similar, consider splitting up the patch into discrete changes that each do one thing. Similarly, if one of the additional considerations is refactoring, try to shift that into a separate patch. | ||
| ===== Tree labels ===== | ===== Tree labels ===== | ||
| Line 155: | Line 173: | ||
| + | ===== New driver ===== | ||
| + | |||
| + | For submitting a new wireless driver the requirements are: | ||
| + | |||
| + | * follow [[https://www.kernel.org/doc/html/latest/process/coding-style.html|Linux kernel coding style]] | ||
| + | * use [[https://www.kernel.org/doc/html/latest/process/license-rules.html|SPDX tags]] | ||
| + | * use either cfg80211 or mac80211, depending on the firmware architecture (no custom 802.11 stack in the driver) | ||
| + | * have firmware images submitted for [[https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/|linux-firmware]] with an acceptable license allowing redistribution | ||
| + | * document Device Tree usage in [[https://www.kernel.org/doc/html/latest/devicetree/bindings/submitting-patches.html|devicetree bindings]] and review them with DT maintainers | ||
| + | * in the commit log/cover letter provide an overview of the driver | ||
| + | * what hardware the driver supports | ||
| + | * what features are supported (client, AP, mesh modes etc) | ||
| + | * for review submit the driver as one file per patch, to make it easier for the reviewers | ||
| + | * example: https://lore.kernel.org/linux-wireless/20200623110000.31559-1-ajay.kathat@microchip.com/ | ||
| + | * final commit (after the review) will be one big patch | ||
| + | * for staging drivers the final patch will be just a small patch moving the driver, example: https://git.kernel.org/linus/5625f965d764 | ||
| + | |||
| + | There's also a list of [[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/LICENSES/preferred|preferred licenses]] available. | ||
| + | |||
| + | Some guidelines to speed up new driver review: | ||
| + | |||
| + | * keep the driver small and simple, more features can be added after the driver is accepted upstream | ||
| + | * use clean understandable code | ||
| + | * use generic kernel frameworks instead of reinventing the wheel | ||
| + | * use generic user space interfaces | ||
| + | * no driver specific user interfaces or hacks | ||
| + | * no .ini style driver configuration files | ||
| + | * avoid using debugfs or nl80211 vendor interfaces | ||
| ===== Examples of a patches ===== | ===== Examples of a patches ===== | ||
| Line 263: | Line 309: | ||
| ==== Signed-off-by missing ==== | ==== 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. | + | 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]]. Do not submit patches unless you have read, understood and agreed to the certificate. |
| ==== Format issues ==== | ==== Format issues ==== | ||
| Line 277: | Line 324: | ||
| commit log message header line text enclosed in parentheses and | commit log message header line text enclosed in parentheses and | ||
| double quotes with no line breaks whatsoever. | double quotes with no line breaks whatsoever. | ||
| + | The fixes lines must be placed just above the signed-off-by lines. | ||
| Example: | Example: | ||
| Line 356: | Line 404: | ||
| More info: http://www.idallen.com/topposting.html | More info: http://www.idallen.com/topposting.html | ||
| + | |||
| + | ==== Do not send HTML mail ==== | ||
| + | |||
| + | linux-wireless mailing list drops all mail using HTML, so don't use it. | ||
| ==== Use RFC or RFT for patches not ready ==== | ==== 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 RFC (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. | + | 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. |
| + | |||
| + | ==== Use Co-developed-by when multiple authors ==== | ||
| + | |||
| + | When a patch has multiple authors you should use Co-developed-by tag: | ||
| + | |||
| + | https://www.kernel.org/doc/html/latest/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by | ||
| + | |||
| + | ==== Maximum of 7-12 patches per patchset ==== | ||
| + | |||
| + | If you want your patches reviewed smoothly submit maximum of 7-12 patches per patchset. If the patches are bigger don't send more than 7 patches. But if they smaller, or trivial patches, 12 patches is ok. But anything more than 12 patches and you will get reviewers grumpy (read: it takes longer to get your patches reviewed and applied). | ||
| + | But you can submit multiple patchsets, just try to throttle it down to avoid bufferbloat in patchwork, for example you can send a new patchset every other day. And don't forget to document the dependencies in the cover letter ("this patchset depends on patchset B"). | ||
| ===== More references ===== | ===== More references ===== | ||
en/developers/documentation/submittingpatches.txt · Last modified: 2024/02/01 20:12 by Jeff Johnson
Page Tools
