1Contributions to OpenHarmony linux kernel project 2========================================== 3 4Sign DCO 5-------- 6 7Before submitting any Contributions to OpenHarmony kernel, you have to sign 8DCO. 9 10See: 11 https://dco.openharmony.io/sign-dco 12 13Steps of submitting patches 14--------------------------- 15 161. Compile and test your patches successfully. 17 You should test your patch in OpenHamrony supported boards, hi3516dv300, 18 etc. 19 202. Generate patches 21 Your patches should be based on top of latest OpenHarmony branch, and 22 should use git-format-patch to generate patches, and if it's a patchset, 23 it's better to use --cover-letter option to describe what the patchset 24 does. 25 26 Using scripts/checkpatch.pl to make sure there's no coding style issue. 27 28 And make sure your patch follow unified OpenHarmony patch format describe 29 below. 30 31 *Tips*: Learn more about linux kernel coding style 32 en: 33 https://gitee.com/openharmony/kernel_linux/blob/master/Documentation/process/coding-style.rst 34 zh: 35 https://gitee.com/openharmony/kernel_linux/blob/master/Documentation/translations/zh_CN/coding-style.rst 36 373. Send patch to OpenHarmony mailing list 38 Use this command to send patches to OpenHarmony kernel mailing list: 39 40 git send-email *.patch -to="kernel@openharmony.io" --suppress-cc=all 41 42 *NOTE*: that you must add --suppress-cc=all if you use git send-email, 43 otherwise the email will be cced to the people in upstream community and 44 mailing lists. 45 46 *Tips*: Subscribe the mailing list 47 https://lists.openatom.io/postorius/lists/kernel.openharmony.io/ 48 49 *See*: How to send patches using git-send-email 50 https://git-scm.com/docs/git-send-email 51 524. Mark "v1, v2, v3 ..." in your patch subject if you have multiple versions 53 to send out. 54 55 Use --subject-prefix="PATCH v2" option to add v2 tag for patchset. 56 git format-patch --subject-prefix="PATCH v2" -1 57 58 Subject examples: 59 Subject: [PATCH v2 01/27] fork: fix some -Wmissing-prototypes warnings 60 Subject: [PATCH v3] ext2: improve scalability of bitmap searching 61 625. Upstream your kernel patch to kernel community is strongly recommended. 63 OpenHarmony will sync up with kernel master timely. 64 656. Sign your work - the Developer's Certificate of Origin 66 As the same of upstream kernel community, you also need to sign your 67 patch. 68 69 See: 70 https://www.kernel.org/doc/html/latest/process/submitting-patches.html 71 72 The sign-off is a simple line at the end of the explanation for the 73 patch, which certifies that you wrote it or otherwise have the right to 74 pass it on as an open-source patch. The rules are pretty simple: if you 75 can certify the below: 76 77 Developer's Certificate of Origin 1.1 78 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 79 80 By making a contribution to this project, I certify that: 81 82 (a) The contribution was created in whole or in part by me and I have 83 the right to submit it under the open source license indicated in 84 the file; or 85 86 (b The contribution is based upon previous work that, to the best of 87 my knowledge, is covered under an appropriate open source license 88 and I have the right under that license to submit that work with 89 modifications, whether created in whole or in part by me, under 90 the same open source license (unless I am permitted to submit under 91 a different license), as indicated in the file; or 92 93 (c) The contribution was provided directly to me by some other person 94 who certified (a), (b) or (c) and I have not modified it. 95 96 (d) I understand and agree that this project and the contribution are 97 public and that a record of the contribution (including all 98 personal information I submit with it, including my sign-off) is 99 maintained indefinitely and may be redistributed consistent with 100 this project or the open source license(s) involved. 101 102 then you just add a line saying: 103 104 Signed-off-by: Random J Developer <random@developer.example.org> 105 106 using your real name (sorry, no pseudonyms or anonymous contributions.) 107 108Use unified patch format 109------------------------ 110 111Reasons: 112 1131. long term maintainability 114 OpenHarmony will merge massive patches. If all patches are merged by 115 casual changelog format without a unified format, the git log will be 116 messy, and then it's hard to figure out the original patch. 117 1182. kernel upgrade 119 We definitely will upgrade our OpenHarmony kernel in someday, using 120 strict patch management will alleviate the pain to migrate patches 121 during big upgrade. 122 1233. easy for script parsing 124 Keyword highlighting is necessary for script parsing. 125 126Patch format definition 127----------------------- 128 129[M] stands for "mandatory" 130[O] stands for "option" 131$category can be: bug preparation, bugfix, perf, feature, doc, other... 132 133If category is feature, then we also need to add feature name like below: 134 category: feature 135 feature: YYY (the feature name) 136 137If the patch is related to CVE or issue/bugzilla, then we need add the 138corresponding tag like below (In general, it should include at least one 139of the following): 140 CVE: $cve-id or NA 141 issue: $issue-id or NA 142 bugzilla: $bug-id or NA 143 144issue: https://gitee.com/openharmony/kernel_linux/issues 145 146Additional changelog should include at least one of the flollwing: 147 1) Why we should apply this patch 148 2) What real problem in product does this patch resolved 149 3) How could we reproduce this bug or how to test 150 4) Other useful information for help to understand this patch or problem 151 152The detail information is very useful for porting patch to another kenrel 153branch. 154 1551. stable patch 156 stable inclusion [M] 157 from $stable-version [M] 158 commit $id [M] 159 bugzilla: $bug-id [O] 160 issue: $issue-id [O] 161 CVE: $cve-id [O] 162 163 additional changelog [O] 164 165 -------------------------------- 166 167 original changelog 168 169 Signed-off-by: $your_name <$your_mail> [M] 170 171 ($stable-version would be stable-4.19.156, stable-4.19.157, etc... 172 $id would be stable commit) 173 1742. mainline patch: 175 176 mainline inclusion [M] 177 from $mainline-version [M] 178 commit $id [M] 179 category: $category [M] 180 bugzilla: $bug-id [O] 181 issue: $issue-id [O] 182 CVE: $cve-id [O] 183 184 additional changelog [O] 185 186 -------------------------------- 187 188 original changelog 189 190 Signed-off-by: $your_name <$your_mail> [M] 191 192 ($mainline-version could be mainline-5.6, mainline-5.10, etc... 193 $id would be mainline commit) 194 1953. ohos patch 196 ohos inclusion [M] 197 category: $category [M] 198 bugzilla: $bug-id or NA [O] 199 issue: $issue-id or NA [O] 200 CVE: $cve-id or NA [O] 201 202 -------------------------------- 203 204 changelog 205 206 Signed-off-by: $your_name <$your_mail> [M] 207 208Examples 209-------- 210 211mainline inclusion 212from mainline-4.10 213commit 0becc0ae5b42828785b589f686725ff5bc3b9b25 214category: bugfix 215issue: 1000 216CVE: NA 217 218The patch fixes a BUG_ON in the product: injecting single bit ECC error 219to memory before system boot use hardware inject tools, which cause a 220large amount of CMCI during system booting . 221 222[ 1.146580] mce: [Hardware Error]: Machine check events logged 223[ 1.152908] ------------[ cut here ]------------ 224[ 1.157751] kernel BUG at kernel/timer.c:951! 225[ 1.162321] invalid opcode: 0000 [#1] SMP 226... 227 228------------------------------------------------- 229 230original changelog 231 232<original S-O-B> 233Signed-off-by: Zhang San <zhangsan@163.com> 234Tested-by: Li Si <lisi@163.com> 235 236Email Client - Thunderbird Settings 237----------------------------------- 238 239If you are newly developer in the kernel community, it is highly recommended 240to use thunderbird mail client. 241 2421. Thunderbird Installation 243 Get English version Thunderbird from http://www.mozilla.org/ and install 244 it on your system. 245 246 Download url: https://www.thunderbird.net/en-US/thunderbird/all/ 247 2482. Settings 249 2.1 Use plain text format instead of HTML format 250 Options -> Account Settings -> Composition & Addressing, do *NOT* 251 select "Compose message in HTML format". 252 253 2.2 Editor Settings 254 Tools->Options->Advanced->Config editor. 255 256 - To bring up the thunderbird's registry editor, and set: 257 "mailnews.send_plaintext_flowed" to "false". 258 - Disable HTML Format: Set "mail.identity.id1.compose_html" to 259 "false". 260 - Enable UTF8: Set "prefs.converted-to-utf8" to "true". 261 - View message in UTF-8: Set "mailnews.view_default_charset" to 262 "UTF-8". 263 - Set mailnews.wraplength to 9999 for avoiding auto-wrap 264 265Linux kernel 266============ 267 268There are several guides for kernel developers and users. These guides can 269be rendered in a number of formats, like HTML and PDF. Please read 270Documentation/admin-guide/README.rst first. 271 272In order to build the documentation, use ``make htmldocs`` or 273``make pdfdocs``. The formatted documentation can also be read online at: 274 275 https://www.kernel.org/doc/html/latest/ 276 277There are various text files in the Documentation/ subdirectory, 278several of them using the Restructured Text markup notation. 279 280Please read the Documentation/process/changes.rst file, as it contains the 281requirements for building and running the kernel, and information about 282the problems which may result by upgrading your kernel. 283