User Tools

Site Tools


en:users:drivers:ath10k: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:users:drivers:ath10k:submittingpatches [2017/06/14 08:06]
Kalle Valo [Patch flow] Mention about ath-current, add the example from sources page, fix outdated link
en:users:drivers:ath10k:submittingpatches [2020/08/26 14:40] (current)
Kalle Valo Fix title formatting for Hardware families
Line 8: Line 8:
       * Cc: [[linux-wireless@vger.kernel.org]] ​       * Cc: [[linux-wireless@vger.kernel.org]] ​
  
-Preferably use [[en/​users/​drivers/​ath10k/​sources|ath.git master branch]] as the baseline for patches. Other trees can be used as well, but then the chances of conflicts are higher. ​+Preferably use [[en/​users/​drivers/​ath10k/​sources|ath.git master branch]] as the baseline for patches. Other trees can be used as well, but then the chances of conflicts are higher. 
 + 
 +It's important that linux-wireless is CCed on the patches, otherwise it won't be in patchwork and the maintainer won't see it. You can follow the state of ath10k patch review from patchwork:​ 
 + 
 +[[https://​patchwork.kernel.org/​project/​linux-wireless/​list/?​state=*&​q=ath10k]]
  
 More info about submitting patches: ​ More info about submitting patches: ​
         * [[en/​developers/​Documentation/​SubmittingPatches|linux-wireless submitting patches instructions]] ​         * [[en/​developers/​Documentation/​SubmittingPatches|linux-wireless submitting patches instructions]] ​
-        * [[en/​developers/​Documentation/​git-guide|linux-wireless git guide]] ​+        * [[en/​developers/​Documentation/​git-guide|linux-wireless git guide]] 
 +        * [[https://​www.kernel.org/​doc/​html/​latest/​process/​submitting-patches.html|Linux kernel submitting patches]] 
 +        * [[https://​medium.com/​@steveamaza/​how-to-write-a-proper-git-commit-message-e028865e5791|How to write proper git commit messages]] 
 +        * [[https://​lkml.kernel.org/​r/​20150314075357.GA8319@gmail.com|Ingo Molnar'​s points about commit logs]]
  
 ==== Guidelines ==== ==== Guidelines ====
Line 18: Line 25:
 Guidelines for patches are: Guidelines for patches are:
    
-          ​* MUST follow [[https://​www.kernel.org/​doc/​html/​latest/​process/​submitting-patches.html|Documentation/​SubmittingPatches]] +  ​* MUST follow [[https://​www.kernel.org/​doc/​html/​latest/​process/​submitting-patches.html|Documentation/​SubmittingPatches]] 
-          * MUST be compiler warning free.  +  * MUST follow [[en/​users/​Drivers/​ath10k/​CodingStyle|ath10k coding style]] 
-          * MUST be sparse warning free.  +  * MUST be compiler and sparse warning free.  
-          Commit log MUST not be empty.  +  [[https://​www.kernel.org/​pub/​software/​scm/​git/​docs/​git-send-email.html|git send-email]] SHOULD ​be used to submit the patch to avoid any formatting issues
-          The commit ​log MUST answer the question "​Why?"​:  +  Patchsets SHOULD contain no more than 12 patches and include a cover letter.  
-             * Describe the motivation behind the bug.  +  * Commit ​log MUST [[#​answer_to_why|answer the question "​Why?"​]]
-             ​How does it change the functionality from user's point of view?  +  Commit log MUST not be empty
-             * Does it fix a bug? If it does, please describe the bug (doesn'​t need to be long). Also if there'​s a public bug report add a link to the bug report.  +  Commit ​log MUST have [[#​tested-on_tag|Tested-on tags]]
-             ​If a problem has been found during code review and doesn'​t fix a known issues, mention that in the commit ​log. +  SHOULD use [[https://www.kernel.org/​doc/html/​latest/​process/​submitting-patches.html#​using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes|Reported-by:​ and Tested-by: tags]] if others have reported the issue
-             ​Ingo Molnar has written ​[[https://lkml.kernel.org/​r/20150314075357.GA8319@gmail.com|a nice description]] about what maintainers are looking from a commit log.  +  * SHOULD use [[https://​www.kernel.org/​doc/​html/​latest/​process/​submitting-patches.html#​describe-changes|Fixestag]] if it fixes a regression caused by known commit
-          *   ​If ​others have reported the issue commit log SHOULD use Reported-byand Tested-bytags.  +  * SHOULD be //mostly// checkpatch clean (though not all patchworks warnings make sense), it's RECOMMENDED to test patches with [[en/​users/​Drivers/​ath10k/​CodingStyle#​checking_code|ath10k-check]] ​as that will disable the useless warnings.
-          * SHOULD be //mostly// checkpatch clean (though not all patchworks warnings make sense):  +
-            * Patches SHOULD be sent with git send-email tool.  +
-            * Patchsets SHOULD contain no more than 12 patches.  +
-            * Patches SHOULD follow [[en/​users/​Drivers/​ath10k/​CodingStyle|ath10k coding style]]  +
-            * It's RECOMMENDED to test patches with [[en/​users/​Drivers/​ath10k/​CodingStyle#​checking_code|ath10k-check]] ​+
  
 The terminology is from [[http://​www.ietf.org/​rfc/​rfc2119.txt|http://​www.ietf.org/​rfc/​rfc2119.txt]] ​ The terminology is from [[http://​www.ietf.org/​rfc/​rfc2119.txt|http://​www.ietf.org/​rfc/​rfc2119.txt]] ​
 +
 +
 +==== Answer to "​Why?"​ ====
 +
 +The commit log needs to describe the motivation behind the bug, in other words provide the background information why the patch is needed and why is it needed the way it is.
 +
 +  * How does it change the functionality from user's point of view? 
 +  * Does it fix a bug? If it does, please describe the bug (doesn'​t necessarily need to be long). Also if there'​s a public bug report add a link to the bug report or email describing the issue. ​
 +  * If a problem has been found during code review and doesn'​t fix a known issue, mention that in the commit log this is a theoretical fix.
 +
 +Ingo Molnar has written [[https://​lkml.kernel.org/​r/​20150314075357.GA8319@gmail.com|a nice description]] about what maintainers are looking from a commit log, read that to understand more about commit logs.
 +
 +==== Hardware families ====
 +
 +ath10k supports multiple hardware families:
 +
 +  * QCA988X PCI Wave 1 AP devices
 +
 +  * QCA9884 PCI Wave 2 AP devices ​
 +
 +  * QCA4019 part of IPQ4019 AP SoC
 +
 +  * QCA6174 PCI mobile devices
 +
 +  * QCA6174 SDIO mobile devices
 +
 +For each of these families have their own firmware branch with different interfaces and possibly different functionality. So then writing a patch for ath10k it's not enough to think about just one family and instead all families need to be taken into account. Otherwise risk of regressions on other families increases significantly.
 +
 +To speed up patch acceptance the commit log should explain what families are affected and what families are not, and why. If that is not done that task will be left for the driver mantainer to do and that will slow down the review significantly.
 +
 +==== Tested-on tag ====
 +
 +As there are so many different hardware families, to make it clear on what hardware and firmware the patch is tested on please use the Tested-on tag. It's similar as Fixes tag, just informing the testing information. The format is:
 +
 +  Tested-on: <​hwname>​ <​hwversion>​ <bus> <​fwversion>​
 +
 +Add this information after the commit log text, but before the s-o-b lines, and adding an empty line between Tested-on and s-o-b tags. There can be (and is very much preferred!) to have multiple Tested-on tags, each tag for every hardware tested.
 +
 +Few examples:
 +
 +<​code>​
 +Tested-on: WCN3990 hw1.0 SNOC WLAN.HL.3.1-01040-QCAHLSWMTPLZ-1
 +Tested-on: QCA6174 hw3.2 SDIO WLAN.RMH.4.4.1-00029
 +Tested-on: QCA6174 hw3.2 PCI WLAN.RM.4.4.1-00110-QCARMSWP-1
 +Tested-on: QCA9888 hw2.0 PCI 10.4-3.10-00047
 +</​code>​
 +
 +Tested-on tag should be in every patch, as non-trivial patches should not be submitted without testing. For trivial patches it's ok to skip Tested-on tag but then it should say "​Compile tested only".
 +
  
 ==== Patch flow ==== ==== Patch flow ====
en/users/drivers/ath10k/submittingpatches.1497427611.txt.gz · Last modified: 2017/06/14 08:06 (external edit)