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
Next revisionBoth sides next revision
zh:submitting-patches [2019/01/30 07:10] – [提交补丁] lujimmyzh:submitting-patches [2020/03/08 15:52] – [10. 签署工作] superice
Line 1: Line 1:
 ====== 提交补丁 ====== ====== 提交补丁 ======
-请首先阅读[[docs/guide-developer:faq-development|Development FAQ]] and [[docs/guide-developer:submittingpatches-tomerge|How to Get Your Change Into OpenWrt]]。+扩展阅读 
 +  * [[docs:guide-developer:working-with-git-email|使用git send-email提交补丁]] 
 +  * 如果你希望使用GitHub也请阅读[[docs:guide-developer:working-with-github-pr|使用GitHub提交修改]]。
  
-补丁可以通过推送向Github或邮件列表提交。+补丁可以通过邮件列表提交,也可以使用GitHub合并请求提交。
  
-提交操作需遵循以下原则:+提交补丁时,您需遵循以下原则:
  
   * 请为每次推送使用不同的git分支,如果您是通过网页编辑文件,GitHub将自动完成该操作。   * 请为每次推送使用不同的git分支,如果您是通过网页编辑文件,GitHub将自动完成该操作。
-  * 使用祈使句描述提交主题和信息,如“增加对X的支持”,而不“增加了对X的支持”+  * 使用祈使句描述提交主题和信息,"add support for X"而不是"added support for X"
  
   * **格式化代码**   * **格式化代码**
Line 15: Line 17:
   * **提交主题**    * **提交主题** 
     * 在提交时必须根据您所做的修改确定一个前缀     * 在提交时必须根据您所做的修改确定一个前缀
-      * **kernel:** 适用于kernel和kmod(kernel module)的软件包+      * **kernel:** 适用于kernel和kmod(内核模块)的软件包
       * **package name:** 适用于软件包        * **package name:** 适用于软件包 
       * **device architecture:** 适用设备。如, **mvebu:** 或 **ramips: add support to example_eval board**        * **device architecture:** 适用设备。如, **mvebu:** 或 **ramips: add support to example_eval board** 
       * **tool name:** 适用于工具       * **tool name:** 适用于工具
-      * **build:** 适用于无明确目普通版本 +      * **build:** 修改Openrt构建框架中除了/toolchain(交叉编译工具链)之外部分。 
-    * 长度不能多于50个字符+    * 长度__不能多于50个字符__
     * 必须描述提交的变化内容及提交的必要性。\\ 尽管要简明扼要的描述并不容易,但描写得当的总结无疑应该做到。     * 必须描述提交的变化内容及提交的必要性。\\ 尽管要简明扼要的描述并不容易,但描写得当的总结无疑应该做到。
     * 在前缀后请不要大写第一个单词     * 在前缀后请不要大写第一个单词
Line 27: Line 29:
   * **提交描述**    * **提交描述** 
     * 每行长度不能多于75个字符     * 每行长度不能多于75个字符
-    * 内容将提交至资源修改日志中因此您者解释您为什么提交\\ 包括您修复的错误症状(日志信息,错误信息等), 这对于那些想要通过查找提交日志来修复问题的人将至关重要\\ 如果是一个修复编译失败的补丁,请包含失败相关的部分日志。 +    * 提交描述将会被保存进码的修改目录__这个描述当能开发解释提交原因__\\ 包括您修复的错误症状(比如日志信息,错误信息等), 这对于那些想要通过查找提交日志来修复问题的人将至关重要\\ 如果是一个修复编译错误的补丁,请包含编译错误中最相关的部分。 
-    * 如果您添加了对新硬件的支持,提交描述中此硬件进行简短描述并说明如将OpenWrt安装到硬件。可访问 [[https://git.openwrt.org/?p=openwrt/openwrt.git&a=search&h=HEAD&st=commit&s=add+support+for|recent additions]] 查看更多示例。+    * 如果您添加了对新硬件的支持,提交描述中应包含设备配置的描述并简要说明如将OpenWrt安装到该设备。可访问 [[https://git.openwrt.org/?p=openwrt/openwrt.git&a=search&h=HEAD&st=commit&s=add+support+for|近期添加的设备]] 查看更多示例。
  
-  * **所有提交应该包含 ''%%Signed-off-by: My Name <my@email.address>%%'' 在此写下您的真实姓名和真实的电子邮件地址**,依照 [[http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst?id=HEAD#n416|第11章:Linux内核补丁指南]]。 +  * **所有提交应该包含 ''%%Signed-off-by: My Name <my@email.address>%%'' 在此写下您的__真实姓名__和真实的电子邮件地址**。请阅读 [[http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst?id=HEAD#n416|第11章:Linux内核补丁指南]]了解您在留下这句话时所声明满足的义务。 
-    * 在git命令行中使用以下代码,可自动完成该操作。<code>git commit --signoff</code>+    * 在git命令行中使用以下代码,可自动完成该操作
  
-  栏 **必须** 与"Signed-off-by:" 一致。 +<code bash> 
 +git commit --signoff 
 +</code> 
 + 
 +  提交(Author) **必须** 与"Signed-off-by:" 一致。 
     * 如果您使用GitHub编辑文件并提交,您必须在GitHub设置中“Name”栏填写您的真实姓名,同时在"Signed-off-by:"中填写您Github帐户的首要邮件地址。     * 如果您使用GitHub编辑文件并提交,您必须在GitHub设置中“Name”栏填写您的真实姓名,同时在"Signed-off-by:"中填写您Github帐户的首要邮件地址。
-    * 如果您在PC本地编辑文件并提交,通过以代码设置您的姓名和邮件地址<code>+    * 如果您在PC本地编辑文件并提交,您需要使用面的命令设置您的姓名和邮件地址: 
 + 
 +<code bash>
 git config --global user.name "my name" git config --global user.name "my name"
-git config --global user.email "my@email.address"</code> +git config --global user.email "my@email.address" 
-===== 使用Github =====+</code>
  
-您可以在 [[https://github.com/openwrt/openwrt|这里]] 找到源代码Github镜像.\\  +===== 补丁合并及补丁代码分支生命周期 ===== 
-您可以在Github网页上分支一个公共资源库然后复制分支到您的电脑,用您所更改的内容创建分支并以Pull请求的方式推给Github+我们鼓励高频提交者主导他们自己的补丁代码分支,以便汇集由他们负责和(或)创建的补丁。旦补丁代码分支经过审查和测试就可以提议将其包含在主分支中。 
 +  - 补丁代码分支随时都可能被合并分支中 
 +  - 错误修复将直接合并到主分支 
 +  - 合并请求(Pull request)可以从任何途径发到补丁邮件列表只要补丁满足要求且提交格式正确,就会被考虑合并。 
 +  - 补丁分支可以作为项目的一部分托管于本项目git服务器、其他个人服务器或GitHub上
  
-如果您不知如何完成操作,请继续阅读\\+===== 补丁检查表 ===== 
 +  - 补丁是一整条提交 ( 多条提交记录需要先进行合并(squash)可参考[[docs:guide-developer:working-with-github-pr#squashing_commits|这里]]了解具体操作 
 +  - 标题少于50个字符 
 +  - 标题后应当有一行空行 
 +  - 补丁描述的每一行少于75个字符 
 +  - 描述应当解释修改的内容 
 +  - 描述还应当解释修改的原因 
 +  - 请确保描述的内容有意义 
 +  - Signoff应当使用真实姓名 
 +  - Signoff也需要使用真实邮件地址 
 +  - 如果这个补丁来自第三人,请保留原作者的Signoff行 
 +  - 补丁发送者、作者的名字和邮件应当与Signoff行中的真实姓名和邮件一致。 
  
-建一个Github户,不可以您可以从LEDE源码获得公众可以用于在Github上的互动交流。+===== DTS检查表 ===== 
 + 
 +  - 不要忘记添加适当的开源许可证,推荐使用 ''SPDX-License-Identifier: GPL-2.0-or-later OR MIT ''[[https://github.com/openwrt/openwrt/commit/221d3e023451cad0b60b8a47e8b788d6368108c2#diff-7ecb7639c5199e391573618b0e444894|详情]] 
 +  - 删除LED节点中所有的''default-state = "off"'' ([[https://github.com/openwrt/openwrt/commit/0d23fd2ab29a66f5d03187db4fac3e396b4f3b62|详情]]) 
 +  - 如果您要添加MTD Flash布局并且''label = "firmware"''或者节点名称为''firmware@xyz'', 请检查您是否添加了适当的compatible属性(如果可用) [[https://github.com/openwrt/openwrt/pull/1586/commits/22c1d69e63a3e80c41baf3941d5e6deb2019d039|详情]] 
 +  - 如果可能,尝试将一些LED用于[[https://github.com/openwrt/openwrt/blob/master/package/base-files/files/etc/diag.sh|diag.sh]]中的系统状态指示 [[https://github.com/openwrt/openwrt/blob/master/target/linux/ath79/dts/qca9533_tplink_tl-wr841-v11.dts#L13|示例]] 
 +  - 节点名称应反映设备的功能,而不是其型号。有关常用节点名称的示例,请查阅[[https://github.com/devicetree-org/devicetree-specification/blob/master/source/devicetree-basics.rst#generic-names-recommendation|第2.2.2节 通用名称议]] 
 +  - 删除除“memory”和“cpu”节点外的所有[[https://github.com/devicetree-org/devicetree-specification/blob/master/source/devicetree-basics.rst#device_type-deprecated|已弃用"device_type"]]属性。 
 + 
 +===== 准备和提交补丁给OpenWrt的深入过程 ===== 
 + 
 +基于 [[https://www.kernel.org/doc/html/latest/process/submitting-patches.html|​Linux内核补丁提交指南]]. 
 + 
 +OpenWrt直在不断改进。我们希望尽可能多的人为这一点做出贡献。如果你发现改变是有用的,一定要设法把它纳入项目中。这样做可以使OpenWrt得到改进,并且有助于将您的更改转发到将来的版本中。 
 + 
 +对于希望向OpenWrt提交更改的人或公司,如果你不熟悉“系统”,这个过程有时会令人畏惧。 
 + 
 +本文档试图制定一种程序,使人们能够以最有效的方式提交补丁。 
 + 
 +重复这些步骤是很重要的: 
 + 
 +  * 听听别人的想法。 
 +  * 谈谈你正在解决的问题和你提出的解决方案。 
 +  * 编写有用的补丁,包括文档。 
 +  * 测试、测试、测试。 
 + 
 +在哪里交流: 
 + 
 +  * 谷歌找到与你的问题有关的东西 
 +  * 维基: [[:start|OpenWrt wiki]] 
 +  * 邮件列表 
 +  * 论坛: [[https://forum.openwrt.org]] 
 +  * IRC irc.freenode.net,频道#openwrt和 #openwrt-devel 
 +  * TRAC ​​https://dev.openwrt.org/ 问题/错误/变更跟踪系统。(Trac现在关闭,只保留存档的目的。) 
 +  * Github - ​http://github.com/openwrt - 代码开发主线和问题跟踪已经搬到这里。 
 + 
 +===== 补丁说明文档 ===== 
 +通常最好先记录自己在做什么,然后再做。文档编制过程通常会揭示可能的改进。请及时更新文档。 
 +===== 创建和提交更改(补丁) ===== 
 +在提交补丁前,请仔细阅读 [[:zh/submitting-patches#补丁检查表|补丁检查表]],并根据列表逐项检查补丁。 
 + 
 +对于外部软件包的补丁程序,请参阅[[docs:guide-developer:build-system:use-patches-with-buildsystem]]上的quilt howto。 
 + 
 +请阅读​[[https://www.kernel.org/doc/html/v4.11/process/email-clients.html|电子邮件客端发送/获取补丁]]以了解如何确保电子邮件客户端会破坏您的补丁。 
 +==== 1. 创建补丁 ===== 
 + 
 +OpenWRT的所有更改都以补丁的形式出现。 
 + 
 +补丁应基于根目录,而不应位于任何较低的子目录中。 
 + 
 +请确保您的补丁不包括任何额外文件, 确保在生成补丁后对其进行检查,以确保准确性。 
 + 
 +如果您的更改产生大量增量,则可能需要研究将其拆分为单个补丁,这些补丁会在逻辑阶段进行修改。 这将有助于其他OpenWrt开发人员更轻松地进行检查,如果您希望补丁被接受,这非常重要。 
 + 
 +可以按照自己的喜好使用不同的工具创建补丁: 
 + 
 +   * Git 
 +   * SVN 
 +   * diff 
 + 
 +为了简化将较小补丁集成到主干中的问题,开发人员还可以向Github主干树中进行拉取请求-这是对早期补丁工作流程的补充。 较大的补丁或需要进一步讨论的补丁仍应发送至openwrt-devel列表,在此处对其进行评审,并在某些时候提交到主干。 
 + 
 + 
 +==== 2. 描述更改内容 ===== 
 + 
 +描述补丁的技术细节。 
 + 
 +要尽可能具体。 最糟糕的描述可能包括诸如“对程序包X的更改”,“对程序包X的错误修复”或“此补丁包括针对平台X的更新。请申请。”之类的内容。 
 + 
 +维护者将感谢以一种“无需修改”格式编写您的补丁描述,这种“无需修改”格式的补丁可以直接作为OpenWRT管理系统的提交使用。见下面的第十三章。 
 + 
 + 
 +如果您的描述开始变长,则表明您可能需要拆补丁。 请参阅下面的第3部分。 
 + 
 +当您提交或重新提交补丁或补丁系列时请包括完整的补丁说明和说明。 不要只是说这是补丁(系列)的N版本。 不要指望补丁合并者会引用较早的补丁版本或引用的URL来查找补丁说明并将其放入补丁中。 即,补丁(系列)及其说明应是独立的,非相互引用的。 这使补丁合并者和审核者都受益。 一些评论者甚至可能没有收到补丁的早期版本。 
 + 
 +如果补丁修复了已记录的错误跟踪条目,请按编号引用该错误条目。 
 + 
 + 
 + 
 +==== 3. 拆分更改内容 ===== 
 +将“__逻辑更改__”分开到单个补丁文件中。 
 + 
 +例如,如果您的更改包括单个程序包的错误修复和增强功能,请将这些更改分为两个或多个补丁程序。 
 + 
 +另一方面,如果您对多个文件进行了一次更改,则将这些更改分组到一个补丁中。 因此,单个“__逻辑更改__”包含在单个补丁中。 
 + 
 +如果一个补丁依赖于另一个补丁才能完成更改,只需在补丁说明中注明“此补丁取决于补丁X”。 
 + 
 +如果您不能将补丁集压缩为更小的补丁集,则一次仅发布15个左右,然后等待审核和集成。 
 + 
 +==== 4. 更改内容格式检查 ===== 
 + 
 +检查您的补丁程序是否存在“基本样式”冲突。 否则,只会浪费审阅者的时间,并会拒绝您的补丁,甚至可能不会被阅读。 
 +==== 5. 选择邮件目的地 ===== 
 +请查看Makefile,是否存在MAINTAINER宏。 如果存在,则请给该人发送电子邮件。 除非您有理由不这样做,否则请始终CC openwrt-devel <at> list.openwrt.org。 如果未列出维护者,请将补丁发送到[[https://lists.openwrt.org/mailman/listinfo/openwrt-devel|​主要的OpenWrt开发者的邮件列表]]。 大多数OpenWrt开发人员监视此电子邮件列表,并可以对您的更改发表评论。 
 +==== 6. 不要使MIME类型邮件,不要使用超连接方式,不要压缩补丁,不要使用附件方式,只使用纯文本 ===== 
 + 
 +OpenWrt开发人员需要能够阅读和评论您提交的更改。 对OpenWrt开发人员而言,使用标准的电子邮件工具“引用”您的更改非常重要,这样他们就可以对代码的特定部分进行注释。 
 + 
 +因此,所有补丁都应“内联”提交电子邮件。 警告:如果您选择剪切粘贴,请小心编辑器的自动换行会损坏您的补丁程序。 
 + 
 +不要将补丁附加为MIME附件,或者压缩。许多流行的电子邮件应用程序并不总是将MIME附件作为纯文本发送,使得无法对代码进行注释。 
 + 
 +例外:如果您的邮件发送者正处理补丁程序,则有人可能会要求你使用MIME重新发送补丁程序。 
 + 
 +Mozilla雷鸟要求您更改电子邮件默认值以发送纯文本电子邮件。[[http://kb.mozillazine.org/Plain_text_e-mail_%28Thunderbird%29|纯文本电子邮件- Thunderbird]]:!:禁用流文本 
 + 
 + 
 +==== 7. 邮件大小 ===== 
 + 
 +较大的更改不适用于邮件列表和某些维护者。 如果未压缩的补丁程序大小超过300 kB,则最好将补丁程序存储在可访问Internet的服务器,并提供指向补丁程序URL (链接) 
 +==== 8. 不要灰心,重新提交 ===== 
 + 
 +提交更改后,请耐心等待。 如果开发人员喜欢你的更改并应用它,它将在源代码管理系统中显示为新修订。 
 + 
 +但是,如果你的更改未出现在源代码管理系统中,则可能有多种原因。 缩小这些原因,纠正错误,然后提交更新的更改是你的工作。 
 + 
 +有时,开发人员可能会“丢弃”你的补丁,而有或没有评论。 这就是系统的本质。 如果你的补丁程序被删除,则可能是由于: 
 + 
 +  * 你的补丁不适用于最新的OpenWrt版本。 
 +  * 你的补丁在openwrt-devel上没有得到充分讨论。 
 +  * 样式问题。 
 +  * 电子邮件格式问题(请重新阅读本节)。 
 +  * 你的更改存在技术问题。 
 +  * 他们收到大量电子邮件,而你的邮件迷失了。 
 +  * 你真烦人。 
 + 
 + 
 +如有疑问,请在openwrt-devel邮件列表上征求意见。 
 + 
 + 
 +==== 9. 在邮件主题中包含PTACH提示 ===== 
 + 
 +由于openwrt-devel的电子邮件量很高,因此通常会在主题行前加上[PATCH]作为前缀。 这样,OpenWrt开发人员可以更轻松地将补丁与其他电子邮件讨论区分开来,并且还将自动进入补丁工作。 
 + 
 +==== 10. 签署工作 ===== 
 + 
 +为了跟踪谁做了什么,我们对正在通过电子邮件发送的补丁程序使用“签署”程序。 
 + 
 +补丁说明末尾的签名很简单,它证明您写了它,或者有权将它作为开放源代码补丁进行传递。 规则非常简单:如果您可以证明以下内容:
  
-在您的PC上安装git,使用以下代码确保本地git置中配置了正确的姓名和电子邮件地址。\\ 
 <code> <code>
-git config --global user.name "my name" +Developer's Certificate of Origin 1.
-git config --global user.email "my@email.address"+ 
 +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.
 </code> </code>
  
-您或许想要将您喜欢的文本编辑器设为Github默认程序,如果您正使用拥有图形界面的Linux系统,您可以选择**geany**、**kwrite**、**pluma** 或者 **gedit**。\\  +然后你只需加上一句话
-如果您正在使用命令行, **nano** 将是合适的选择. <code>git config --global core.editor "editor-name-here"</code>+
  
-然后,follow高质量的关于 [[https://help.github.com/articles/fork-a-repo/|创建分支库]] 和 [[https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork|在本地创建您的分支副本]] 的Github帮助文档。\\+<code bash> 
 +Signed-off-byRandom J Developer <random@developer.example.org> 
 +</code>
  
-当您完成发相应设备后,您可以使用以下命令来为您的PR创建一个分支: +使用您的真实姓(没化名或匿名
-<code>git checkout -b my-new-branch-name</code> +
-命令中"my-new-branch-name" 仅用于示例, 请为您分支使用一个更直观的称 +
-在此命令后您所提交将以此分支分组。多个不同PR的分支可以共存+
  
-使用以下命令,以便在您已创建支间切换: +如果你是一个包或目标维护者有时你需要稍微修改你接收到的补丁以便合并它们,因为代码你的树和提交者中不是完全相同的。如果你严格遵守规则,你应该向提交人请求重新授权,但这完全是浪费时间和精力。规则(B)允许调整代码,但是更改提交人代码并使他持您的bug是非常不礼貌的。为了解决这个问题,建议您在最后一个签名的头和您的头之添加一行,说明您的更改的性质。虽然没有什么强制性的,这似乎是准备描述与您的邮件和/或名称,所有包围在方括号中,是显而易见的,足以使你清楚,你负责的最后一分钟的变化。例子:
-<code>git checkout my-branch-name</code>+
  
-当您完成修改后,您可以使用以下命令并通过交互界面添加未被跟踪(即新的)文件和更新已存在的文件。+<code bash> 
 +Signed-off-by: Random J Developer <random@developer.example.org> 
 +[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] 
 +Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> 
 +</code>
  
-使用以下命令,可以打开git默认程序以便您添加描述信息: +如果你保持个稳定分支并希望同时信任作者,跟踪更改合并修复,并保护提交者不受投诉,这种做法尤其有用。请注意,在任何情况下,都不能更改作者身份(从报头),因为它是在变更日志中出现的身份
-<code>git commit --signoff</code>  +
-行为提交主题然后空一行接着是您本次提交的描述。 +
-该命令会自动追加行“Signed-off-by:一行后紧跟已设置姓名和邮件地址信息\\ +
-一条完整的提交描述应该像这样:\\  +
-  The best code update. +
-   +
-  This is the best piece of code I have ever submitted. +
-  Signed-off-by: John Doe <John.Doe@test.com>+
  
-您可以使用以下命令将您本地修改发送到您Github资源库 +向后移植者特别注意:在提交消息的顶部(仅在主题行之后)插补丁来源的指示,以方便跟踪,这似乎是一种常见且有的做法。 例如:
- <code>git push --all</code> +
-此期间,会要求您输Github户名及密码+
  
-在代码被上传至您的Github资源库后可以在Github网页版交这个, 具体请查阅关[[https://help.github.com/articles/creating-a-pull-request/|创建一个pull请求]]的文档。\\ +<code bash> 
 +Date:   Wed Jul 25 15:14:50 2012 +0300 
 +    [generic] add missing symbols 
 +    [backport r12345] 
 +</code> 
 + 
 +无论采用哪种格式此信息都可以为跟踪您的树的人们以及试图对树中的错误进行故障排除的人们供宝贵的帮助。 
 + 
 +更方便的开发人员,git可以自动添加签名: 
 + 
 +<code bash> 
 +git commit -s 
 +</code> 
 + 
 +==== 11. 什么时候使用"Acked-by:"和"Cc:" ===== 
 +The Signed-off-by: tag indicates that the signer was involved in the development of the patch, or that he/she was in the patch's delivery path. 
 + 
 +If a person was not directly involved in the preparation or handling of a patch but wishes to signify and record their approval of it then they can arrange to have an Acked-by: line added to the patch's changelog. 
 + 
 +Acked-by: is often used by the maintainer of the affected code when that maintainer neither contributed to nor forwarded the patch. 
 + 
 +Acked-by: is not as formal as Signed-off-by:. It is record that the acker has at least reviewed the patch and has indicated acceptance. Hence patch mergers will sometimes manually convert an acker's "yep, looks good to me" into an Acked-by:. 
 + 
 +Acked-by: does not necessarily indicate acknowledgement of the entire patch. For example, if a patch affects multiple packages and has an Acked-by: from one package maintainer then this usually indicates acknowledgement of just the part which affects that maintainer's code. Judgment should be used here. 
 + 
 +If a person has had the opportunity to comment on a patch, but has not provided such comments, you may optionally add a "Cc:" tag to the patch. This is the only tag which might be added without an explicit action by the person it names. This tag documents that potentially interested parties have been included in the discussion.
  
-===== 通过邮件发送补丁 =====+==== 12. 使用 "Reported-by:", "Tested-by:" and "Reviewed-by:" ===== 
 +If this patch fixes a problem reported by somebody else, consider adding a Reported-by: tag to credit the reporter for their contribution. Please note that this tag should not be added without the reporter's permission, especially if the problem was not reported in a public forum. That said, if we diligently credit our bug reporters, they will, hopefully, be inspired to help us again in the future.
  
-向 [[https://​lists.openwrt.org/​mailman/​listinfo/​openwrt-devel|development mailing list]]发送一封邮件。 所有的补丁需要与以下页面所列内容保持一致的格式,[[https://patchwork.ozlabs.org/project/​openwrt/list/|patchwork]]。 +A Tested-bytag indicates that the patch has been successfully tested (in some environment) by the person namedThis tag informs maintainers that some testing has been performed, provides a means to locate testers for future patches, and ensures credit for the testers.
-如果补丁未在patchwork中列出,则该补丁将不会得到处理。 +
-如邮件客户端会添加空格并打乱格式或添加不可打印字符时,我们强烈推荐使用[[https://​git-scm.com/​docs/​git-send-email|git send-email]]。 +
-===== 梳理提交 ===== +
-提交到PR或通过电子邮件发送的提交应该描述您想合并的所有修改,而不是修复您的原始PR评论中的所有问题。+
  
-所以,您需要花费时间重写或梳理您的提交,最终形成合理数量的提交。+Reviewed-by:, instead, indicates that the patch has been reviewed and found acceptable according to the Reviewer's Statement:
  
-使用git命令行 
-修改您的开发文件夹 
-使用以下命令来查看您的分支, 
-<code>git branch -a</code> 
-分支信息将以以下形式展示: 
 <code> <code>
-  best_code_update +Reviewer's statement of oversight
-* master</code>+
  
-使用以下命令,您想将PR转换为您的开发分支: +By offering my Reviewed-by: tag, I state that:
-<code>git checkout best_code_update</code>+
  
-使用以下命令,您可以查看Git日志以便计算您想梳理的提交数量: +(a) I have carried out a technical review of this patch to 
-<code>git log</code>+    evaluate its appropriateness and readiness for inclusion into 
 +    OpenWrt.
  
-使用以下命令,删除提交。X是您想删除的最新提交的数量,该命令仅会删除提交: +(b) Any problems, concerns, or questions relating to the patch 
-<code>git reset HEAD~X</code>+    have been communicated back to the submitter. I am satisfied 
 +    with the submitter's response to my comments.
  
-使用以下命令,可以将文件重新加入git跟踪: +(c) While there may be things that could be improved with this 
-<code>git add -i</code>+    submission, I believe that it is, at this time, (1) a 
 +    worthwhile modification to OpenWrt, and (2) free of known 
 +    issues which would argue against its inclusion.
  
-使用以下命令,重新提交: +(d) While I have reviewed the patch and believe it to be sound, I 
-<code>git commit --signoff</code>+    do not (unless explicitly stated elsewhere) make any 
 +    warranties or guarantees that it will achieve its stated 
 +    purpose or function properly in any given situation. 
 +</code>
  
-使用以下命令可以发送更新分支到Github,在PR中的提交将会被自动更新: +A Reviewed-by tag is a statement of opinion that the patch is an appropriate modification of OpenWrt without any remaining serious technical issues. Any interested reviewer (who has done the work) can offer a Reviewed-by tag for a patch. This tag serves to give credit to reviewers and to inform maintainers of the degree of review which has been done on the patch. Reviewed-bytags, when supplied by reviewers known to understand the subject area and to perform thorough reviews, will normally increase the likelihood of your patch getting into OpenWrt.
-<code>git push -f</code>  +
-==== 避免混乱的建议====+
  
-您可以通过以下代码使用 **interactive rebase** 来整合、重排或编辑您的提交及相关信息,X为需要编辑的提交数量。<code>git rebase -i HEAD~X</code> +==== 13. 规范补丁格式 ===== 
-===== 补丁合并及树的生命周期 =====+The canonical patch subject line is:
  
-我们鼓励高频的提交者主导他们自己的分级树,以便汇集由他们负责和(或)创建的补丁。一旦树经过审查和测试,就可以提议将其包含在主分支中。+<code bash> 
 +Subject: [PATCH 001/123] [section] summary phrase 
 +</code>
  
-  - 树随时都可能被合并到主分支中 +The canonical patch message body contains the following: 
-  - 错误修复将直接合并到主分支 +   * A "from" line specifying the patch author. 
-  - PR可以从任何途径发送到补丁邮件列表。只要树的质量好且提交格式正确,将始终考虑包含该PR。 +   * An empty line. 
-  分级树可以作为项目的一部分被git基础架构、专用服务器或GitHub托管 +   * The body of the explanation, which will be copied to the permanent changelog to describe this patch. 
-===== 补丁检查表 ===== +   * The "Signed-off-by:" lines, described above, which will also go in the changelog. 
-  单个提交 (如上所述,多个提交会被挤压) +   * A marker line containing simply ''%%---%%''. 
-  主题长度小于50个字符 +   Any additional comments not suitable for the changelog. 
-  主题后空一行 +   The actual patch (diff output).
-  每行描述长度小于75个字符 +
-  - 使用 **什么** 描述来解释修改的内容 +
-  - 使用 **为什么** 来解释修改的原因   +
-  - 描述应该是有实际意义的 +
-  - Signoff行包含真实的姓名 +
-  - Signoff行包含真实的邮件地址 +
-  - If it's a third-party patch, then preserve Signoff line from the original author +
-  - Sender/Author name and email address matches Signoff line's real name and email address +
  
-===== DTS检查表 ===== +The Subject line format makes it very easy to sort the emails alphabetically by subject line pretty much any email reader will support that since because the sequence number is zero-padded, the numerical and alphabetic sort is the same. 
-  - Don't forget to add proper license, consider adding ''SPDX-License-Identifier: GPL-2.0-or-later OR MIT'' ([[https://github.com/openwrt/openwrt/commit/221d3e023451cad0b60b8a47e8b788d6368108c2#diff-7ecb7639c5199e391573618b0e444894|details]]) + 
-  Remove all ocurrencies of ''default-state = "off"'' properties under your LED nodes ([[https://github.com/openwrt/openwrt/commit/0d23fd2ab29a66f5d03187db4fac3e396b4f3b62|details]]) +The "section" in the email's Subject should identify which section of OpenWrt is being patched. Some example sections are: 
-  If you're adding MTD flash layoutand you've ''label = "firmware"'' or node with the name ''firmware@xyz'', please check that you've added proper ''compatible'' property (if applicable) ([[https://github.com/openwrt/openwrt/pull/1586/commits/22c1d69e63a3e80c41baf3941d5e6deb2019d039|details]]) +   [a specific target name] 
-  - If it's possible try to dedicate some of the LEDs for system status indication in [[https://github.com/openwrt/openwrt/blob/master/package/base-files/files/etc/diag.sh|diag.sh]] ([[https://github.com/openwrt/openwrt/blob/master/target/linux/ath79/dts/qca9533_tplink_tl-wr841-v11.dts#L13|example]]) +   [a specific package name] 
-  - The name of a node should reflect the function of the device and not its model. Examples for generic node names can be found in Section [[https://github.com/devicetree-org/devicetree-specification/blob/master/source/devicetree-basics.rst#generic-names-recommendation|2.2.2 Generic Names Recommendation]] + 
-  Remove all [[https://github.com/devicetree-org/devicetree-specification/blob/master/source/devicetree-basics.rst#device_type-deprecated|deprecated "device_type"]] propertiesunless for "memory" or "cpu" nodes+The "summary phrase" in the email's Subject should concisely describe the patch which that email contains. The "summary phrase" should not be a filename. Do not use the same "summary phrase" for every patch in a whole patch series (where a "patch series" is an ordered sequence of multiple, related patches). 
 + 
 +Bear in mind that the "summary phrase" of your email becomes a globally-unique identifier for that patch. It propagates all the way into the source code management system changelog. The "summary phrase" may later be used in developer discussions which refer to the patch. People will want to google for the "summary phrase" to read discussion regarding that patch. It will also be the only thing that people may quickly see when, two or three months later, they are going through perhaps thousands of patches using source code management browsing tools. 
 + 
 +For these reasons, the "summary" must be no more than 70-75 characters, and it must describe both what the patch changes, as well as why the patch might be necessary. It is challenging to be both succinct and descriptive, but that is what a well-written summary should do. 
 + 
 +The "summary phrasemay be prefixed by tags enclosed in square brackets: "Subject: [PATCH tag] <summary phrase>". The tags are not considered part of the summary phrase, but describe how the patch should be treated. Common tags might include a version descriptor if the multiple versions of the patch have been sent out in response to comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for comments. If there are four patches in a patch series the individual patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures that developers understand the order in which the patches should be applied and that they have reviewed or applied all of the patches in the patch series. 
 + 
 +Some example Subjects: 
 + 
 +<code bash> 
 +Subject: [PATCH] e2fsprogs: Bump to 1.41.3 
 + 
 +Subject: [PATCH] x86 genericswitch to 3.3 
 + 
 +Subject: [PATCHv2 001/207] ar71xx enable sysupgrade on the WRT160Nl 
 +</code> 
 + 
 +The "from" line must be the very first line in the message body, and has the form: 
 + 
 +<code bash> 
 +From: Original Author <author@example.com
 +</code> 
 + 
 +The "from" line specifies who will be credited as the author of the patch in the permanent changelog. If the "from" line is missingthen the "From:line from the email header will be used to determine the patch author in the changelog. 
 + 
 +The explanation body will be committed to the permanent source changelog, so should make sense to competent reader who has long since forgotten the immediate details of the discussion that might have led to this patch. Including symptoms of the failure which the patch addresses (kernel log messages, oops messages, etc.) is especially useful for people who might be searching the commit logs looking for the applicable patch. If a patch fixes a compile failure, it may not be necessary to include _all_ of the compile failures; just enough that it is likely that someone searching for the patch can find it. As in the "summary phrase", it is important to be both succinct as well as descriptive. 
 + 
 +The ''%%---%%'' marker line serves the essential purpose of marking for patch handling tools where the changelog message ends. 
 + 
 +One good use for the additional comments after the ''%%---%%'' marker is for a diffstat, to show what files have changed, and the number of inserted and deleted lines per file. A diffstat is especially useful on bigger patches. Other comments relevant only to the moment or the maintainer, not suitable for the permanent changelog, should also go here. A good example of such comments might be "patch changelogs" which describe what has changed between the v1 and v2 version of the patch. 
 + 
 +See more details on the proper patch format in the following References. 
 + 
 +===== 补丁监控 ===== 
 +发送到开发邮件列表的补丁可以在Patchwork网站跟踪​[[https://patchwork.ozlabs.org/project/openwrt/list/]]
 + 
 +===== 参考 ====== 
 +   * Andrew Morton, "The perfect patch" (tpp). 
 +      https://www.ozlabs.org/~akpm/stuff/tpp.txt 
 +      * ​http://userweb.kernel.org/~akpm/stuff/tpp.txt 
 +   * Jeff Garzik, "Linux kernel patch submission format"
 +      * ​http://linux.yyz.us/patch-format.html 
 +   * Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer"
 +      * ​http://www.kroah.com/log/linux/maintainer.html 
 +      * ​http://www.kroah.com/log/linux/maintainer-02.html 
 +      * ​http://www.kroah.com/log/linux/maintainer-03.html 
 +      * ​http://www.kroah.com/log/linux/maintainer-04.html 
 +      * ​http://www.kroah.com/log/linux/maintainer-05.html 
 +   * NO!!!! No more huge patch bombs to linux-kernel@… people! 
 +      * ​http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2 
 +   * Linus Torvalds's mail on the canonical patch format: 
 +      * ​​http://lkml.org/lkml/2005/4/7/183 
 +   * Andi Kleen, "On submitting kernel patches" 
 +      * Some strategies to get difficult or controversial changes in. 
 +      * ​http://halobates.de/on-submitting-patches.pdf 
 + 
 +===== 附加信息 ===== 
 + 
 +  * 注意行长度限制(80字符)。 
 +  * 使用./scripts/checkpatch.pl脚本检查你的补丁- 可能有误报。
  • Last modified: 2021/10/15 08:32
  • by bobafetthotmail