User Tools

Site Tools


en:developers:documentation:submittingpatches

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
en:developers:documentation:submittingpatches [2017/05/18 12:15]
Kalle Valo [Whitespace damage] Rename section Whitespace damage to Format issues
en:developers:documentation:submittingpatches [2017/08/03 04:47] (current)
Kalle Valo Add "Commit log does not answer "Why?""
Line 248: Line 248:
 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. 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]]+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. 
 + 
 +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.
  
 ===== More patch work references ===== ===== More patch work references =====
en/developers/documentation/submittingpatches.1495109755.txt.gz · Last modified: 2017/05/18 12:15 by Kalle Valo