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 [2020/10/12 13:19] Kalle Valo [New driver] overview of the driver |
en:developers:documentation:submittingpatches [2022/05/18 05:13] Kalle Valo [Commit title is wrong] should be informative and unique |
||
|---|---|---|---|
| Line 13: | Line 13: | ||
| ===== Prior to sending patches ===== | ===== Prior to sending patches ===== | ||
| - | Please **DO NOT** PGP sign patches sent to //linux-wireless//. The reason is that signing patches will encapsulate them into MIME and thereby mangle the patch. Also, please note that we prefer patches inline rather than attachments. | + | Please **DO NOT** PGP sign patches sent to public lists. The reason is that signing patches will encapsulate them into MIME and thereby mangle the patch. Also, please note that we prefer patches inline rather than attachments. And no HTML mail, our lists reject those automatically. |
| + | |||
| + | And carefully read [[http://www.infradead.org/~dwmw2/email.html|our email etiquette]], that saves everyone's time. | ||
| Line 23: | Line 25: | ||
| CC: linux-wireless@vger.kernel.org, Other Developers</code> | CC: linux-wireless@vger.kernel.org, Other Developers</code> | ||
| - | For wireless-drivers patches (except mac80211_hwsim) send patches as: | + | For wireless drivers patches (except mac80211_hwsim) send patches as: |
| <code>To: linux-wireless@vger.kernel.org | <code>To: linux-wireless@vger.kernel.org | ||
| Line 57: | Line 59: | ||
| ===== 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 81: | Line 83: | ||
| 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 94: | Line 96: | ||
| 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 109: | Line 128: | ||
| Alternatively you can specify the exact tree you are targetting by adding the name of the git tree inside PATCH brackets: | 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 | + | <code>[PATCH wireless] mac80211: fix foo |
| - | [PATCH mac80211-next] mac80211: implement very-cool-feature | + | [PATCH wireless-next] mac80211: implement very-cool-feature |
| - | [PATCH wireless-drivers] ath10k: fix foo | + | [PATCH wireless] ath10k: fix foo |
| - | [PATCH wireless-drivers-next] ath10k: implement awesome-feature | + | [PATCH wireless-next] ath10k: implement awesome-feature |
| </code> | </code> | ||
| Line 175: | Line 194: | ||
| There's also a list of [[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/LICENSES/preferred|preferred licenses]] available. | 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 304: | Line 332: | ||
| Fixes: c742e623e941 ("mwifiex: sdio card reset enhancement") | Fixes: c742e623e941 ("mwifiex: sdio card reset enhancement") | ||
| + | Here's how one can configure git to provide the fixes tag in correct format: | ||
| + | |||
| + | $ git config --global --add alias.fixes 'show -q --format=fixes' | ||
| + | $ git config --global --add pretty.fixes 'Fixes: %h ("%s")' | ||
| + | $ git config --global --add core.abbrev 12 | ||
| + | $ git fixes ba9177fcef21 | ||
| + | Fixes: ba9177fcef21 ("ath11k: Add basic WoW functionalities") | ||
| ==== Commit reference is wrong ==== | ==== Commit reference is wrong ==== | ||
| Line 330: | Line 365: | ||
| ==== Commit title is wrong ==== | ==== 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: | + | The correct format for the commit title is name of driver, followed by a colon, followed by a space and then followed by the actual title. Also the title should be informative and unique, so something like "fix a bug" is not a good title. |
| + | |||
| + | For examples uou can use ''git log'' to check older commits and see what prefix was used: | ||
| <code> | <code> | ||
| Line 385: | Line 422: | ||
| ==== 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 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. | + | 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) in the subject. This way the maintainer can easily see that the patch should not be applied yet and saves maintainer's time. |
| + | |||
| + | Examples: | ||
| + | |||
| + | [PATCH RFC] ath11k: enable power save mode always | ||
| + | [PATCH RFT] ath10k: sdio: always use DMA transfers | ||
| ==== Use Co-developed-by when multiple authors ==== | ==== Use Co-developed-by when multiple authors ==== | ||
en/developers/documentation/submittingpatches.txt · Last modified: 2024/02/01 20:12 by Jeff Johnson
Page Tools
