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/26 06:08]
Kalle Valo [Commit title is wrong] Fix spelling
en:developers:documentation:submittingpatches [2018/06/14 08:10] (current)
Kalle Valo [More patch work references] Change title, "patch work" is easy to confuse with patchwork (the tool)
Line 35: Line 35:
 ===== Checking state of patches from patchwork ===== ===== Checking state of patches from patchwork =====
  
-All wireless patches are tracked in [[https://​patchwork.kernel.org/​project/​linux-wireless/​list/​|linux-wireless patchwork project]] ​(only exception being ath10k which has its own [[https://​patchwork.kernel.org/​project/​ath10k/​list/?​state=*|ath10k 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:+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=*]] [[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.+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: Different patchwork states and their meanings:
Line 111: Line 111:
 ===== 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 232: Line 232:
 ==== Changelog missing ==== ==== Changelog missing ====
  
-When sending a new version of a patch or patchset you should **always** add a changelog so that maintainer can easily what has changed.+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 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 switch ''​--cover-letter'':​+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   git format-patch --subject-prefix="​PATCH v2" --cover-letter
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 ==== ==== Fixes line is incorrect ====
Line 306: Line 306:
 </​code>​ </​code>​
  
-===== More patch work references =====+==== 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 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. 
 + 
 + 
 +===== 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 ​
Line 314: Line 349:
   * [[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]] ​
   * [[https://​www.ozlabs.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)]]
en/developers/documentation/submittingpatches.1495778896.txt.gz · Last modified: 2017/05/26 06:08 by Kalle Valo