diff --git a/README.md b/README.md index e053ca064714936623363f501cb81f32190dab6d..dccf87e9a22c0c170e17b2c950b50b415314bc4f 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,284 @@ # kernel_linux_5.15 -#### 介绍 -{**以下是 Gitee 平台说明，您可以替换此简介** -Gitee 是 OSCHINA 推出的基于 Git 的代码托管平台（同时支持 SVN）。专为开发者提供稳定、高效、安全的云端软件开发协作平台 -无论是个人、团队、或是企业，都能够用 Gitee 实现代码托管、项目管理、协作开发。企业项目请看 [https://gitee.com/enterprises](https://gitee.com/enterprises)} +Contributions to OpenHarmony linux kernel project +========================================== -#### 软件架构 -软件架构说明 +Sign DCO +-------- +Before submitting any Contributions to OpenHarmony kernel, you have to sign +DCO. -#### 安装教程 +See: + https://dco.openharmony.io/sign-dco -1. xxxx -2. xxxx -3. xxxx +Steps of submitting patches +--------------------------- -#### 使用说明 +1. Compile and test your patches successfully. + You should test your patch in OpenHamrony supported boards, hi3516dv300, + etc. -1. xxxx -2. xxxx -3. xxxx +2. Generate patches + Your patches should be based on top of latest OpenHarmony branch, and + should use git-format-patch to generate patches, and if it's a patchset, + it's better to use --cover-letter option to describe what the patchset + does. -#### 参与贡献 + Using scripts/checkpatch.pl to make sure there's no coding style issue. -1. Fork 本仓库 -2. 新建 Feat_xxx 分支 -3. 提交代码 -4. 新建 Pull Request + And make sure your patch follow unified OpenHarmony patch format describe + below. + *Tips*: Learn more about linux kernel coding style + en: + https://gitee.com/openharmony/kernel_linux/blob/master/Documentation/process/coding-style.rst + zh: + https://gitee.com/openharmony/kernel_linux/blob/master/Documentation/translations/zh_CN/coding-style.rst -#### 特技 +3. Send patch to OpenHarmony mailing list + Use this command to send patches to OpenHarmony kernel mailing list: -1. 使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md -2. Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com) -3. 你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目 -4. [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目 -5. Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help) -6. Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/) + git send-email *.patch -to="kernel@openharmony.io" --suppress-cc=all + + *NOTE*: that you must add --suppress-cc=all if you use git send-email, + otherwise the email will be cced to the people in upstream community and + mailing lists. + + *Tips*: Subscribe the mailing list + https://lists.openatom.io/postorius/lists/kernel.openharmony.io/ + + *See*: How to send patches using git-send-email + https://git-scm.com/docs/git-send-email + +4. Mark "v1, v2, v3 ..." in your patch subject if you have multiple versions + to send out. + + Use --subject-prefix="PATCH v2" option to add v2 tag for patchset. + git format-patch --subject-prefix="PATCH v2" -1 + + Subject examples: + Subject: [PATCH v2 01/27] fork: fix some -Wmissing-prototypes warnings + Subject: [PATCH v3] ext2: improve scalability of bitmap searching + +5. Upstream your kernel patch to kernel community is strongly recommended. + OpenHarmony will sync up with kernel master timely. + +6. Sign your work - the Developer's Certificate of Origin + As the same of upstream kernel community, you also need to sign your + patch. + + See: + https://www.kernel.org/doc/html/latest/process/submitting-patches.html + + The sign-off is a simple line at the end of the explanation for the + patch, which certifies that you wrote it or otherwise have the right to + pass it on as an open-source patch. The rules are pretty simple: if you + can certify the below: + + Developer's Certificate of Origin 1.1 + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I have + the right to submit it under the open source license indicated in + the file; or + + (b The contribution is based upon previous work that, to the best of + my knowledge, is covered under an appropriate open source license + and I have the right under that license to submit that work with + modifications, whether created in whole or in part by me, under + the same open source license (unless I am permitted to submit under + a different license), as indicated in the file; or + + (c) The contribution was provided directly to me by some other person + who certified (a), (b) or (c) and I have not modified it. + + (d) I understand and agree that this project and the contribution are + public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + + then you just add a line saying: + + Signed-off-by: Random J Developer + + using your real name (sorry, no pseudonyms or anonymous contributions.) + +Use unified patch format +------------------------ + +Reasons: + +1. long term maintainability + OpenHarmony will merge massive patches. If all patches are merged by + casual changelog format without a unified format, the git log will be + messy, and then it's hard to figure out the original patch. + +2. kernel upgrade + We definitely will upgrade our OpenHarmony kernel in someday, using + strict patch management will alleviate the pain to migrate patches + during big upgrade. + +3. easy for script parsing + Keyword highlighting is necessary for script parsing. + +Patch format definition +----------------------- + +[M] stands for "mandatory" +[O] stands for "option" +$category can be: bug preparation, bugfix, perf, feature, doc, other... + +If category is feature, then we also need to add feature name like below: + category: feature + feature: YYY (the feature name) + +If the patch is related to CVE or issue/bugzilla, then we need add the +corresponding tag like below (In general, it should include at least one +of the following): + CVE: $cve-id or NA + issue: $issue-id or NA + bugzilla: $bug-id or NA + +issue: https://gitee.com/openharmony/kernel_linux/issues + +Additional changelog should include at least one of the flollwing: + 1) Why we should apply this patch + 2) What real problem in product does this patch resolved + 3) How could we reproduce this bug or how to test + 4) Other useful information for help to understand this patch or problem + +The detail information is very useful for porting patch to another kenrel +branch. + +1. stable patch + stable inclusion [M] + from $stable-version [M] + commit $id [M] + bugzilla: $bug-id [O] + issue: $issue-id [O] + CVE: $cve-id [O] + + additional changelog [O] + + -------------------------------- + + original changelog + + Signed-off-by: $your_name <$your_mail> [M] + + ($stable-version would be stable-4.19.156, stable-4.19.157, etc... + $id would be stable commit) + +2. mainline patch: + + mainline inclusion [M] + from $mainline-version [M] + commit $id [M] + category: $category [M] + bugzilla: $bug-id [O] + issue: $issue-id [O] + CVE: $cve-id [O] + + additional changelog [O] + + -------------------------------- + + original changelog + + Signed-off-by: $your_name <$your_mail> [M] + + ($mainline-version could be mainline-5.6, mainline-5.10, etc... + $id would be mainline commit) + +3. ohos patch + ohos inclusion [M] + category: $category [M] + bugzilla: $bug-id or NA [O] + issue: $issue-id or NA [O] + CVE: $cve-id or NA [O] + + -------------------------------- + + changelog + + Signed-off-by: $your_name <$your_mail> [M] + +Examples +-------- + +mainline inclusion +from mainline-4.10 +commit 0becc0ae5b42828785b589f686725ff5bc3b9b25 +category: bugfix +issue: 1000 +CVE: NA + +The patch fixes a BUG_ON in the product: injecting single bit ECC error +to memory before system boot use hardware inject tools, which cause a +large amount of CMCI during system booting . + +[ 1.146580] mce: [Hardware Error]: Machine check events logged +[ 1.152908] ------------[ cut here ]------------ +[ 1.157751] kernel BUG at kernel/timer.c:951! +[ 1.162321] invalid opcode: 0000 [#1] SMP +... + +------------------------------------------------- + +original changelog + + +Signed-off-by: Zhang San +Tested-by: Li Si + +Email Client - Thunderbird Settings +----------------------------------- + +If you are newly developer in the kernel community, it is highly recommended +to use thunderbird mail client. + +1. Thunderbird Installation + Get English version Thunderbird from http://www.mozilla.org/ and install + it on your system. + + Download url: https://www.thunderbird.net/en-US/thunderbird/all/ + +2. Settings + 2.1 Use plain text format instead of HTML format + Options -> Account Settings -> Composition & Addressing, do *NOT* + select "Compose message in HTML format". + + 2.2 Editor Settings + Tools->Options->Advanced->Config editor. + + - To bring up the thunderbird's registry editor, and set: + "mailnews.send_plaintext_flowed" to "false". + - Disable HTML Format: Set "mail.identity.id1.compose_html" to + "false". + - Enable UTF8: Set "prefs.converted-to-utf8" to "true". + - View message in UTF-8: Set "mailnews.view_default_charset" to + "UTF-8". + - Set mailnews.wraplength to 9999 for avoiding auto-wrap + +Linux kernel +============ + +There are several guides for kernel developers and users. These guides can +be rendered in a number of formats, like HTML and PDF. Please read +Documentation/admin-guide/README.rst first. + +In order to build the documentation, use ``make htmldocs`` or +``make pdfdocs``. The formatted documentation can also be read online at: + + https://www.kernel.org/doc/html/latest/ + +There are various text files in the Documentation/ subdirectory, +several of them using the Restructured Text markup notation. + +Please read the Documentation/process/changes.rst file, as it contains the +requirements for building and running the kernel, and information about +the problems which may result by upgrading your kernel. \ No newline at end of file