This translation is older than the original page and might be outdated. See what has changed.

提交补丁

扩展阅读

补丁可以通过邮件列表提交，也可以使用GitHub合并请求提交。

提交补丁时，您需遵循以下原则：

  • 请为每次推送使用不同的git分支，如果您是通过网页编辑文件，GitHub将自动完成该操作。
  • 使用祈使句描述提交主题和信息，例如“add support for X”而不是“added support for X”。
  • 格式化代码
    • 使用您正在修改文件中相同的缩进方式，使用Tabs还是空格取决于文件剩余部分所采用的方式。
    • 列表依字母顺序排序
  • 提交主题
    • 在提交时必须根据您所做的修改确定一个前缀
      • kernel: 适用于kernel和kmod（内核模块）的软件包
      • package name: 适用于软件包
      • device architecture: 适用设备。如, mvebu: 或 ramips: add support to example_eval board
      • tool name: 适用于工具
      • build: 修改Openrt构建框架中除了/toolchain（交叉编译工具链）之外的部分。
    • 长度不能多于50个字符
    • 必须描述提交的变化内容及提交的必要性。
      尽管要简明扼要的描述并不容易，但描写得当的总结无疑应该做到。
    • 在前缀后请不要大写第一个单词
    • 主题末尾请不要使用句号
  • 提交描述
    • 每行长度不能多于75个字符
    • 提交描述将会被保存进源码的修改目录，这个描述应当能向开发者们解释提交原因
      包括您修复的错误症状（比如日志信息,错误信息等）, 这对于那些想要通过查找提交日志来修复问题的人将至关重要
      如果是一个修复编译错误的补丁，请只包含编译错误中最相关的部分。
    • 如果您添加了对新硬件的支持，提交描述中应包含对设备配置的描述并简要说明如何将OpenWrt安装到该设备。可访问 近期添加的设备 查看更多示例。
  • 所有提交应该包含 Signed-off-by: My Name <my@email.address> 在此写下您的真实姓名和真实的电子邮件地址。请阅读 第11章：Linux内核补丁指南了解您在留下这句话时所声明满足的义务。
    • 在git命令行中使用以下代码，可自动完成该操作：
git commit --signoff
  • 提交者（Author） 必须 与“Signed-off-by:” 一致。
    • 如果您使用GitHub编辑文件并提交，您必须在GitHub设置中“Name”栏填写您的真实姓名，同时在“Signed-off-by:“中填写您Github帐户的首要邮件地址。
    • 如果您在PC本地编辑文件并提交，您需要使用下面的命令设置您的姓名和邮件地址：
git config --global user.name "my name"
git config --global user.email "my@email.address"

补丁合并及补丁代码分支的生命周期

我们鼓励高频的提交者主导他们自己的补丁代码分支，以便汇集由他们负责和（或）创建的补丁。一旦补丁代码分支经过审查和测试，就可以提议将其包含在主分支中。

  1. 补丁代码分支随时都可能被合并到主分支中
  2. 错误修复将直接合并到主分支
  3. 合并请求（Pull request）可以从任何途径发送到补丁邮件列表。只要补丁满足要求且提交格式正确，就会被考虑合并。
  4. 补丁分支可以作为项目的一部分托管于本项目git服务器、其他个人服务器或GitHub上

补丁检查表

  1. 补丁是一整条提交 ( 多条提交记录需要先进行合并（squash）可以参考这里了解具体操作 )
  2. 标题少于50个字符
  3. 标题后应当有一行空行
  4. 补丁描述的每一行少于75个字符
  5. 描述应当解释修改的内容
  6. 描述还应当解释修改的原因
  7. 请确保描述的内容有意义
  8. Signoff应当使用真实姓名
  9. Signoff也需要使用真实邮件地址
  10. 如果这个补丁来自第三人，请保留原作者的Signoff行
  11. 补丁发送者、作者的名字和邮件应当与Signoff行中的真实姓名和邮件一致。

DTS检查表

  1. 不要忘记添加适当的开源许可证，推荐使用 SPDX-License-Identifier: GPL-2.0-or-later OR MIT 详情
  2. 删除LED节点中所有的default-state = “off” (详情)
  3. 如果您要添加MTD Flash布局并且label = “firmware”或者节点名称为firmware@xyz, 请检查您是否添加了适当的compatible属性（如果可用） 详情
  4. 如果可能，尝试将一些LED用于diag.sh中的系统状态指示 示例
  5. 节点名称应反映设备的功能，而不是其型号。有关常用节点名称的示例，请查阅第2.2.2节 通用名称建议
  6. 删除除“memory”和“cpu”节点外的所有已弃用"device_type"属性。

准备和提交补丁给OpenWrt的深入过程

基于 ​Linux内核补丁提交指南.

OpenWrt一直在不断改进。我们希望尽可能多的人为这一点做出贡献。如果你发现改变是有用的，一定要设法把它纳入项目中。这样做可以使OpenWrt得到改进，并且有助于将您的更改转发到将来的版本中。

对于希望向OpenWrt提交更改的个人或公司，如果你不熟悉“系统”，这个过程有时会令人畏惧。

本文档试图制定一种程序，使人们能够以最有效的方式提交补丁。

重复这些步骤是很重要的：

  • 听听别人的想法。
  • 谈谈你正在解决的问题和你提出的解决方案。
  • 编写有用的补丁，包括文档。
  • 测试、测试、测试。

在哪里交流：

补丁说明文档

通常最好先记录自己在做什么，然后再做。文档编制过程通常会揭示可能的改进。请及时更新文档。

创建和提交更改（补丁）

在提交补丁前，请仔细阅读 补丁检查表，并根据列表逐项检查补丁。

对于外部软件包的补丁程序，请参阅use-patches-with-buildsystem上的quilt howto。

请阅读​电子邮件客户端发送/获取补丁，以了解如何确保电子邮件客户端不会破坏您的补丁。

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。 如果未列出维护者，请将补丁发送到​主要的OpenWrt开发者的邮件列表。 大多数OpenWrt开发人员监视此电子邮件列表，并可以对您的更改发表评论。

6. 不要使用MIME类型邮件，不要使用超连接方式，不要压缩补丁，不要使用附件方式，只使用纯文本

OpenWrt开发人员需要能够阅读和评论您提交的更改。 对于OpenWrt开发人员而言，使用标准的电子邮件工具“引用”您的更改非常重要，这样他们就可以对代码的特定部分进行注释。

因此，所有补丁都应“内联”提交电子邮件。 警告：如果您选择剪切粘贴，请小心编辑器的自动换行会损坏您的补丁程序。

不要将补丁附加为MIME附件，或者压缩。许多流行的电子邮件应用程序并不总是将MIME附件作为纯文本发送，使得无法对代码进行注释。

例外：如果您的邮件发送者正在处理补丁程序，则有人可能会要求你使用MIME重新发送补丁程序。

Mozilla雷鸟要求您更改电子邮件默认值以发送纯文本电子邮件。纯文本电子邮件- Thunderbird:!:禁用流文本

7. 邮件大小

较大的更改不适用于邮件列表和某些维护者。 如果未压缩的补丁程序大小超过300 kB，则最好将补丁程序存储在可访问Internet的服务器上，并提供指向补丁程序的URL （链接）

8. 不要灰心，重新提交

提交更改后，请耐心等待。 如果开发人员喜欢你的更改并应用它，它将在源代码管理系统中显示为新修订。

但是，如果你的更改未出现在源代码管理系统中，则可能有多种原因。 缩小这些原因，纠正错误，然后提交更新的更改是你的工作。

有时，开发人员可能会“丢弃”你的补丁，而有或没有评论。 这就是系统的本质。 如果你的补丁程序被删除，则可能是由于：

  • 你的补丁不适用于最新的OpenWrt版本。
  • 你的补丁在openwrt-devel上没有得到充分讨论。
  • 样式问题。
  • 电子邮件格式问题（请重新阅读本节）。
  • 你的更改存在技术问题。
  • 他们收到大量电子邮件，而你的邮件迷失了。
  • 你真烦人。

如有疑问，请在openwrt-devel邮件列表上征求意见。

9. 在邮件主题中包含PTACH提示

由于openwrt-devel的电子邮件流量很高，因此通常会在主题行前加上[PATCH]作为前缀。 这样，OpenWrt开发人员可以更轻松地将补丁与其他电子邮件讨论区分开来，并且还将自动进入补丁工作。

10. 签署工作

为了跟踪谁做了什么，我们对正在通过电子邮件发送的补丁程序使用“签署”程序。

补丁说明末尾的签名很简单，它证明您写了它，或者有权将它作为开放源代码补丁进行传递。 规则非常简单：如果您可以证明以下内容： 

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.

然后你只需加上一句话 

Signed-off-by: Random J Developer <random@developer.example.org>

使用您的真实姓名（没有化名或匿名。）

如果你是一个包或目标维护者，有时你需要稍微修改你接收到的补丁以便合并它们，因为代码在你的树和提交者中不是完全相同的。如果你严格遵守规则，你应该向提交人请求重新授权，但这完全是浪费时间和精力。规则（B）允许您调整代码，但是更改提交人的代码并使他支持您的bug是非常不礼貌的。为了解决这个问题，建议您在最后一个签名的头和您的头之间添加一行，说明您的更改的性质。虽然没有什么强制性的，这似乎是准备描述与您的邮件和/或名称，所有包围在方括号中，是显而易见的，足以使你清楚，你负责的最后一分钟的变化。例子： 

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>

如果你保持一个稳定的分支，并希望同时信任作者，跟踪更改，合并修复，并保护提交者不受投诉，这种做法尤其有用。请注意，在任何情况下，您都不能更改作者的身份（从报头），因为它是在变更日志中出现的身份。

向后移植者的特别注意：在提交消息的顶部（仅在主题行之后）插入补丁来源的指示，以方便跟踪，这似乎是一种常见且有用的做法。 例如： 

Date:   Wed Jul 25 15:14:50 2012 +0300
    [generic] add missing symbols
    [backport r12345]

无论采用哪种格式，此信息都可以为跟踪您的树的人们以及试图对树中的错误进行故障排除的人们提供宝贵的帮助。

对于更方便的开发人员，git可以自动添加签名： 

git commit -s

11. 什么时候使用"Acked-by:"和"Cc:"

Signed-off-by（签署者）：标记表明签名者参与了补丁的开发，或者他/她在补丁的交付路径中。

如果某人未直接参与补丁的准备或处理，但希望表示并记录其批准，则可以安排在补丁的变更日志中添加“ Acked-by：”行。

Acked-by：当受影响的代码的维护者既不贡献也不转发补丁时，通常由该维护者使用。

“ Acked-by：”不如“ Signed-by-by”那么正式。 记录表明，黑客至少已审查了补丁并表示已接受。 因此，补丁合并有时会手动将acker的“是的，对我来说很好”转换为Acked-by:。

Acked-by（认证人）：不一定表示已确认整个补丁。 例如，如果一个补丁影响多个软件包并且从一个软件包维护者处获得了“ Acked-by：”，则通常表示仅确认影响该维护者代码的部分。 此处应使用判断。

如果某人有机会对补丁发表评论，但未提供此类评论，则可以选择在补丁中添加“ Cc：”标签。 这是唯一由其命名的人在没有明确操作的情况下添加的标签。 该标签记录了潜在的利益相关方已包含在讨论中。

12. 使用 "Reported-by:", "Tested-by:" and "Reviewed-by:"

如果此修补程序解决了其他人报告的问题，请考虑添加Reported-by（审阅人）：标签以向报告者的贡献功劳。 请注意，未经记者许可，请勿添加此标签，尤其是如果未在公共论坛上报告此问题。 就是说，如果我们勤奋地向错误报告者致谢，希望他们会在将来受到启发，再次为我们提供帮助。

Tested by（测试者）：标记表示该补丁已由指定的人成功测试（在某些环境中）。 此标签通知维护人员已经执行了一些测试，提供了一种方法来定位测试人员以获取将来的补丁程序，并确保对测试人员的信誉。

Reviewed-by（审阅人）：而是表示该审阅的补丁已根据审阅者声明被接受： 

Reviewer's statement of oversight

By offering my Reviewed-by: tag, I state that:

(a) I have carried out a technical review of this patch to
    evaluate its appropriateness and readiness for inclusion into
    OpenWrt.

(b) Any problems, concerns, or questions relating to the patch
    have been communicated back to the submitter. I am satisfied
    with the submitter's response to my comments.

(c) While there may be things that could be improved with this
    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
    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.

“Reviewed-by（审阅者）”标记是一种意见，认为该补丁是对OpenWrt的适当修改，没有任何严重的技术问题。 任何感兴趣的审阅者（已完成工作）都可以为补丁提供“Reviewed-by（审阅者）”标签。 这个标签可以给评论者带来荣誉，并告知维护者补丁上已完成的审阅程度。 Reviewed-by（审阅者）：标签由已知了解主题领域并进行全面审阅的审阅者提供时，通常会增加您的补丁进入OpenWrt的可能性。

13. 规范补丁格式

规范补丁主题行是： 

Subject: [PATCH 001/123] [section] summary phrase
主题： [ PATCH 001/123 ] [ section ]摘要短语

规范补丁消息正文包含以下内容：

  • “ from”行指定补丁作者。
  • 空行。
  • 说明的主体，它将被复制到永久更改日志中以描述此补丁。
  • 上面描述的“签名人：”行也将出现在变更日志中。
  • 仅包含---标记线。
  • 任何不适合变更日志的其他注释。
  • 实际补丁（差异输出）。

主题行格式使按主题行按字母顺序对电子邮件进行排序非常容易-几乎任何电子邮件阅读器都支持-由于序列号为零填充，因此数字和字母排序相同。

电子邮件主题中的“部分”应标识正在修补OpenWrt的哪个部分。 一些示例部分是：

  • [特定的目标名称]
  • [特定的包裹名称]

电子邮件主题中的“摘要短语”应简明地描述电子邮件所包含的补丁。 “摘要短语”不应是文件名。 请勿对整个补丁系列中的每个补丁使用相同的“摘要短语”（“补丁系列”是多个相关补丁的有序序列）。

请记住，电子邮件的“摘要短语”将成为该补丁程序的全局唯一标识符。 它一直传播到源代码管理系统变更日志。 稍后，“摘要短语”可能会在涉及补丁的开发人员讨论中使用。 人们会希望在Google上搜索“摘要短语”以阅读有关该补丁的讨论。 当两三个月后，当他们使用源代码管理浏览工具来浏览可能成千上万的补丁程序时，这也将是人们很快就会看到的唯一内容。

由于这些原因，“摘要”必须不超过70-75个字符，并且必须描述补丁程序的变化以及为何需要补丁程序。 既要简洁又要具有描述性，这是具有挑战性的，但这是写得很好的总结所要做的。

“摘要短语”可以用方括号括起来的标签作为前缀：“主题：[PATCH标签] <摘要短语>”。 标签不被视为摘要短语的一部分，而是描述了应如何处理补丁。 如果已发出多个补丁版本以响应注释（即“ v1，v2，v3”）或“ RFC ”以表示请求注释，则公共标签可能包括版本描述符。 如果一个补丁系列中有四个补丁，则各个补丁的编号可能会像这样：1 / 4、2 / 4、3 / 4、4 / 4。 这样可确保开发人员了解应应用补丁的顺序，并确保他们已查看或应用了补丁系列中的所有补丁。 

Subject: [PATCH] e2fsprogs: Bump to 1.41.3
 
Subject: [PATCH] x86 generic: switch to 3.3
 
Subject: [PATCHv2 001/207] ar71xx enable sysupgrade on the WRT160Nl
主题： [ PATCH ] e2fsprogs：升至1.41.3
 
主题： [ PATCH ] x86通用：切换到3.3
 
主题： [ PATCHv2 001/207 ] ar71xx在WRT160Nl上启用 sysupgrade

“ from”行必须是消息正文中的第一行，其格式为： 

From: Original Author <author@example.com>

“from”行指定谁将被视为永久更改日志中补丁的作者。 如果缺少“发件人”行，则电子邮件标题中的“发件人：”行将用于确定变更日志中的补丁作者。

解释机构将致力于永久性源变更日志，因此对于长期以来一直忘记可能导致此补丁的讨论的即时细节的资深读者来说，这应该是有意义的。 补丁程序解决的故障症状（内核日志消息，oops消息等）包括在内，这对于可能正在搜索提交日志以寻找适用补丁程序的人员特别有用。 如果修补程序解决了编译失败，则可能不必包括所有的编译失败。 刚好足以使搜索补丁的人可以找到它。 就像在“摘要短语”中一样，既简洁又具有描述性很重要。

---标记行的主要目的是标记更改日志消息结束处的修补程序处理工具。

---标记后的其他注释的一个很好用处是diffstat，用于显示已更改的文件以及每个文件插入和删除的行数。 diffstat在较大的修补程序上特别有用。 其他仅与当下或维护者相关的注释，不适用于永久变更日志，也应在此处进行。 这样的注释的一个很好的例子可能是“补丁更改日志”，它描述了补丁的v1和v2版本之间的更改。

在以下参考中查看有关正确补丁格式的更多详细信息。

补丁监控

发送到开发邮件列表的补丁可以在Patchwork网站跟踪​https://patchwork.ozlabs.org/project/openwrt/list/.

参考

附加信息

  • 注意行长度限制（80字符）。
  • 使用./scripts/checkpatch.pl脚本检查你的补丁- 可能有误报。
This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website.More information about cookies
  • Last modified: 2021/10/15 08:32
  • by bobafetthotmail