1 .. SPDX-License-Identifier: GPL-2.0-or-later 1 .. SPDX-License-Identifier: GPL-2.0-or-later
2 2
3 .. include:: ../disclaimer-zh_CN.rst 3 .. include:: ../disclaimer-zh_CN.rst
4 4
5 .. _cn_submittingpatches: 5 .. _cn_submittingpatches:
6 6
7 :Original: Documentation/process/submitting-pa 7 :Original: Documentation/process/submitting-patches.rst
8 8
9 :译者: 9 :译者:
10 - 钟宇 TripleX Chung <xxx.phy@gmail.com> 10 - 钟宇 TripleX Chung <xxx.phy@gmail.com>
11 - 时奎亮 Alex Shi <alexs@kernel.org> 11 - 时奎亮 Alex Shi <alexs@kernel.org>
12 - 吴想成 Wu XiangCheng <bobwxc@email.cn> 12 - 吴想成 Wu XiangCheng <bobwxc@email.cn>
13 13
14 :校译: 14 :校译:
15 - 李阳 Li Yang <leoyang.li@nxp.com> 15 - 李阳 Li Yang <leoyang.li@nxp.com>
16 - 王聪 Wang Cong <xiyou.wangcong@gmail.com> 16 - 王聪 Wang Cong <xiyou.wangcong@gmail.com>
17 17
18 18
19 提交补丁：如何让你的改动进入内 19 提交补丁：如何让你的改动进入内核
20 ================================ 20 ================================
21 21
22 对于想要将改动提交到 Linux 内核的 22 对于想要将改动提交到 Linux 内核的个人或者公司来说，如果不熟悉“规矩”，
23 提交的流程会让人畏惧。本文档包 23 提交的流程会让人畏惧。本文档包含了一系列建议，可以大大提高你
24 的改动被接受的机会. 24 的改动被接受的机会.
25 25
26 本文档以较为简洁的行文给出了大 26 本文档以较为简洁的行文给出了大量建议。关于内核开发流程如何进行的详细信息，
27 参见： Documentation/translations/zh_CN/pro 27 参见： Documentation/translations/zh_CN/process/development-process.rst 。
28 Documentation/translations/zh_CN/process/submi 28 Documentation/translations/zh_CN/process/submit-checklist.rst 给出了一系列
29 提交补丁之前要检查的事项。设备 29 提交补丁之前要检查的事项。设备树相关的补丁，请参阅
30 Documentation/devicetree/bindings/submitting-p 30 Documentation/devicetree/bindings/submitting-patches.rst 。
31 31
32 本文档假设您正在使用 ``git`` 准备 32 本文档假设您正在使用 ``git`` 准备你的补丁。如果您不熟悉 ``git`` ，最好学习
33 如何使用它，这将使您作为内核开 33 如何使用它，这将使您作为内核开发人员的生活变得更加轻松。
34 34
35 部分子系统和维护人员的树有一些 35 部分子系统和维护人员的树有一些关于其工作流程和要求的额外信息，请参阅
36 Documentation/process/maintainer-handbooks.rst 36 Documentation/process/maintainer-handbooks.rst 。
37 37
38 获取当前源码树 38 获取当前源码树
39 -------------- 39 --------------
40 40
41 如果您手头没有当前内核源代码的 41 如果您手头没有当前内核源代码的存储库，请使用 ``git`` 获取一份。您需要先获取
42 主线存储库，它可以通过以下命令 42 主线存储库，它可以通过以下命令拉取::
43 43
44 git clone git://git.kernel.org/pub/scm/lin 44 git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
45 45
46 但是，请注意，您可能不想直接针 46 但是，请注意，您可能不想直接针对主线树进行开发。大多数子系统维护人员运
47 行自己的树，并希望看到针对这些 47 行自己的树，并希望看到针对这些树准备的补丁。请参见MAINTAINERS文件中子系
48 统的 **T:** 项以查找该树，或者直 48 统的 **T:** 项以查找该树，或者直接询问维护者该树是否未在其中列出。
49 49
50 .. _zh_describe_changes: 50 .. _zh_describe_changes:
51 51
52 描述你的改动 52 描述你的改动
53 ------------ 53 ------------
54 54
55 描述你的问题。无论您的补丁是一 55 描述你的问题。无论您的补丁是一行错误修复还是5000行新功能，都必须有一个潜在
56 的问题激励您完成这项工作。说服 56 的问题激励您完成这项工作。说服审阅者相信有一个问题值得解决，让他们读完第一段
57 后就能明白这一点。 57 后就能明白这一点。
58 58
59 描述用户可见的影响。直接崩溃和 59 描述用户可见的影响。直接崩溃和锁定是相当有说服力的，但并不是所有的错误都那么
60 明目张胆。即使在代码审阅期间发 60 明目张胆。即使在代码审阅期间发现了这个问题，也要描述一下您认为它可能对用户产
61 生的影响。请记住，大多数Linux安 61 生的影响。请记住，大多数Linux安装运行的内核来自二级稳定树或特定于供应商/产品
62 的树，只从上游精选特定的补丁， 62 的树，只从上游精选特定的补丁，因此请包含任何可以帮助您将更改定位到下游的内容：
63 触发的场景、DMESG的摘录、崩溃描 63 触发的场景、DMESG的摘录、崩溃描述、性能回归、延迟尖峰、锁定等。
64 64
65 质量优化和权衡。如果您声称在性 65 质量优化和权衡。如果您声称在性能、内存消耗、堆栈占用空间或二进制大小方面有所
66 改进，请包括支持它们的数据。但 66 改进，请包括支持它们的数据。但也要描述不明显的成本。优化通常不是零成本的，而是
67 在CPU、内存和可读性之间进行权衡 67 在CPU、内存和可读性之间进行权衡；或者，做探索性的工作，在不同的工作负载之间进
68 行权衡。请描述优化的预期缺点， 68 行权衡。请描述优化的预期缺点，以便审阅者可以权衡成本和收益。
69 69
70 提出问题之后，就要详细地描述一 70 提出问题之后，就要详细地描述一下您实际在做的技术细节。对于审阅者来说，用简练的
71 英语描述代码的变化是很重要的， 71 英语描述代码的变化是很重要的，以验证代码的行为是否符合您的意图。
72 72
73 如果您将补丁描述写成“标准格式 73 如果您将补丁描述写成“标准格式”，可以很容易地作为“提交日志”放入Linux的源代
74 码管理系统 ``git`` 中，那么维护人 74 码管理系统 ``git`` 中，那么维护人员将非常感谢您。
75 参见 :ref:`zh_the_canonical_patch_format` 75 参见 :ref:`zh_the_canonical_patch_format` 。
76 76
77 每个补丁只解决一个问题。如果你 77 每个补丁只解决一个问题。如果你的描述开始变长，这就表明你可能需要拆分你的补丁。
78 请见 :ref:`zh_split_changes` 。 78 请见 :ref:`zh_split_changes` 。
79 79
80 提交或重新提交补丁或补丁系列时 80 提交或重新提交补丁或补丁系列时，请包括完整的补丁说明和理由。不要
81 只说这是补丁（系列）的第几版。 81 只说这是补丁（系列）的第几版。不要期望子系统维护人员引用更早的补丁版本或引用
82 URL来查找补丁描述并将其放入补丁 82 URL来查找补丁描述并将其放入补丁中。也就是说，补丁（系列）及其描述应该是独立的。
83 这对维护人员和审阅者都有好处。 83 这对维护人员和审阅者都有好处。一些审阅者可能甚至没有收到补丁的早期版本。
84 84
85 用祈使句描述你的变更，例如“make 85 用祈使句描述你的变更，例如“make xyzzy do frotz”而不是“[This patch]make
86 xyzzy do frotz”或“[I]changed xyzzy to do 86 xyzzy do frotz”或“[I]changed xyzzy to do frotz”，就好像你在命令代码库改变
87 它的行为一样。 87 它的行为一样。
88 88
89 如果您想要引用一个特定的提交， 89 如果您想要引用一个特定的提交，不要只引用提交的SHA-1 ID。还请包括提交的一行
90 摘要，以便于审阅者了解它是关于 90 摘要，以便于审阅者了解它是关于什么的。例如::
91 91
92 Commit e21d2170f36602ae2708 ("video: r 92 Commit e21d2170f36602ae2708 ("video: remove unnecessary
93 platform_set_drvdata()") removed the u 93 platform_set_drvdata()") removed the unnecessary
94 platform_set_drvdata(), but left the v 94 platform_set_drvdata(), but left the variable "dev" unused,
95 delete it. 95 delete it.
96 96
97 您还应该确保至少使用前12位SHA-1 ID 97 您还应该确保至少使用前12位SHA-1 ID。内核存储库包含 *许多* 对象，使较短的ID
98 发生冲突的可能性很大。记住，即 98 发生冲突的可能性很大。记住，即使现在不会与您的六个字符ID发生冲突，这种情况
99 也可能在五年后改变。 99 也可能在五年后改变。
100 100
101 如果该变更的相关讨论或背景信息 101 如果该变更的相关讨论或背景信息可以在网上查阅，请加上“Link:”标签指向它。例如
102 你的补丁修复了一个缺陷，需要添 102 你的补丁修复了一个缺陷，需要添加一个带有URL的标签指向邮件列表存档或缺陷跟踪器
103 的相关报告；如果该补丁是由一些 103 的相关报告；如果该补丁是由一些早先邮件列表讨论或网络上的记录引起的，请指向它。
104 104
105 当链接到邮件列表存档时，请首选l 105 当链接到邮件列表存档时，请首选lore.kernel.org邮件存档服务。用邮件中的
106 ``Message-ID`` 头（去掉尖括号）可以 106 ``Message-ID`` 头（去掉尖括号）可以创建链接URL。例如::
107 107
108 Link: https://lore.kernel.org/r/30th.anniv 108 Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
109 109
110 请检查该链接以确保可用且指向正 110 请检查该链接以确保可用且指向正确的邮件。
111 111
112 不过，在没有外部资源的情况下， 112 不过，在没有外部资源的情况下，也要尽量让你的解释可理解。除了提供邮件列表存档或
113 缺陷的URL之外，还要需要总结该补 113 缺陷的URL之外，还要需要总结该补丁的相关讨论要点。
114 114
115 如果补丁修复了特定提交中的错误 115 如果补丁修复了特定提交中的错误，例如使用 ``git bisct`` 发现了一个问题，请使用
116 带有前12个字符SHA-1 ID的“Fixes:”标 116 带有前12个字符SHA-1 ID的“Fixes:”标签和单行摘要。为了简化解析脚本，不要将该
117 标签拆分为多行，标签不受“75列 117 标签拆分为多行，标签不受“75列换行”规则的限制。例如::
118 118
119 Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu 119 Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
120 120
121 下列 ``git config`` 设置可以让 ``git lo 121 下列 ``git config`` 设置可以让 ``git log``, ``git show`` 增加上述风格的显示格式::
122 122
123 [core] 123 [core]
124 abbrev = 12 124 abbrev = 12
125 [pretty] 125 [pretty]
126 fixes = Fixes: %h (\"%s\") 126 fixes = Fixes: %h (\"%s\")
127 127
128 使用示例:: 128 使用示例::
129 129
130 $ git log -1 --pretty=fixes 54a4f0239f 130 $ git log -1 --pretty=fixes 54a4f0239f2e
131 Fixes: 54a4f0239f2e ("KVM: MMU: make k 131 Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
132 132
133 .. _zh_split_changes: 133 .. _zh_split_changes:
134 134
135 拆分你的改动 135 拆分你的改动
136 ------------ 136 ------------
137 137
138 将每个 **逻辑更改** 拆分成一个单 138 将每个 **逻辑更改** 拆分成一个单独的补丁。
139 139
140 例如，如果你的改动里同时有bug修 140 例如，如果你的改动里同时有bug修正和性能优化，那么把这些改动拆分到两个或
141 者更多的补丁文件中。如果你的改 141 者更多的补丁文件中。如果你的改动包含对API的修改，并且增加了一个使用该新API
142 的驱动，那么把这些修改分成两个 142 的驱动，那么把这些修改分成两个补丁。
143 143
144 另一方面，如果你将一个单独的改 144 另一方面，如果你将一个单独的改动做成多个补丁文件，那么将它们合并成一个
145 单独的补丁文件。这样一个逻辑上 145 单独的补丁文件。这样一个逻辑上单独的改动只被包含在一个补丁文件里。
146 146
147 需要记住的一点是，每个补丁的更 147 需要记住的一点是，每个补丁的更改都应易于理解，以便审阅者验证。每个补丁都应该
148 对其价值进行阐述。 148 对其价值进行阐述。
149 149
150 如果有一个补丁依赖另外一个补丁 150 如果有一个补丁依赖另外一个补丁来完成它的改动，那没问题。直接在你的补
151 丁描述里指出 **“这个补丁依赖某 151 丁描述里指出 **“这个补丁依赖某补丁”** 就好了。
152 152
153 在将您的更改划分为一系列补丁时 153 在将您的更改划分为一系列补丁时，要特别注意确保内核在应用系列中的每个补丁之后
154 都能正常构建和运行。使用 ``git bis 154 都能正常构建和运行。使用 ``git bisect`` 来追踪问题的开发者可能会在任何地方分
155 割你的补丁系列；如果你在中间引 155 割你的补丁系列；如果你在中间引入错误，他们不会感谢你。
156 156
157 如果你不能将补丁系列浓缩得更小 157 如果你不能将补丁系列浓缩得更小，那么每次大约发送出15个补丁，然后等待审阅
158 和集成。 158 和集成。
159 159
160 检查你的更改风格 160 检查你的更改风格
161 ---------------- 161 ----------------
162 162
163 检查您的补丁是否违反了基本样式 163 检查您的补丁是否违反了基本样式规定，详细信息参见
164 Documentation/translations/zh_CN/process/codin 164 Documentation/translations/zh_CN/process/coding-style.rst
165 中找到。如果不这样做，只会浪费 165 中找到。如果不这样做，只会浪费审阅者的时间，并且会导致你的补丁被拒绝，甚至
166 可能没有被阅读。 166 可能没有被阅读。
167 167
168 一个重要的例外是在将代码从一个 168 一个重要的例外是在将代码从一个文件移动到另一个文件时——在这种情况下，您不应
169 该在移动代码的同一个补丁中修改 169 该在移动代码的同一个补丁中修改移动的代码。这清楚地描述了移动代码和您的更改
170 的行为。这大大有助于审阅实际差 170 的行为。这大大有助于审阅实际差异，并允许工具更好地跟踪代码本身的历史。
171 171
172 在提交之前，使用补丁样式检查程 172 在提交之前，使用补丁样式检查程序检查补丁（scripts/check patch.pl）。不过，
173 请注意，样式检查程序应该被视为 173 请注意，样式检查程序应该被视为一个指南，而不是作为人类判断的替代品。如果您
174 的代码看起来更好，但有违规行为 174 的代码看起来更好，但有违规行为，那么最好别管它。
175 175
176 检查者报告三个级别： 176 检查者报告三个级别：
177 177
178 - ERROR：很可能出错的事情 178 - ERROR：很可能出错的事情
179 - WARNING：需要仔细审阅的事项 179 - WARNING：需要仔细审阅的事项
180 - CHECK：需要思考的事情 180 - CHECK：需要思考的事情
181 181
182 您应该能够判断您的补丁中存在的 182 您应该能够判断您的补丁中存在的所有违规行为。
183 183
184 选择补丁收件人 184 选择补丁收件人
185 -------------- 185 --------------
186 186
187 您应该总是知会任何补丁相应代码 187 您应该总是知会任何补丁相应代码的子系统维护人员；查看
188 维护人员文件和源代码修订历史记 188 维护人员文件和源代码修订历史记录，以了解这些维护人员是谁。脚本
189 scripts/get_maintainer.pl在这个步骤中非 189 scripts/get_maintainer.pl在这个步骤中非常有用。如果您找不到正在工作的子系统
190 的维护人员，那么Andrew Morton（akpm@l 190 的维护人员，那么Andrew Morton（akpm@linux-foundation.org）将充当最后的维护
191 人员。 191 人员。
192 192
193 您通常还应该选择至少一个邮件列 193 您通常还应该选择至少一个邮件列表来接收补丁集的副本。linux-kernel@vger.kernel.org
194 是所有补丁的默认列表，但是这个 194 是所有补丁的默认列表，但是这个列表的流量已经导致了许多开发人员不再看它。
195 在MAINTAINERS文件中查找子系统特定 195 在MAINTAINERS文件中查找子系统特定的列表；您的补丁可能会在那里得到更多的关注。
196 不过，请不要发送垃圾邮件到无关 196 不过，请不要发送垃圾邮件到无关的列表。
197 197
198 许多与内核相关的列表托管在vger.ke 198 许多与内核相关的列表托管在vger.kernel.org上；您可以在
199 http://vger.kernel.org/vger-lists.html 上找 199 http://vger.kernel.org/vger-lists.html 上找到它们的列表。不过，也有与内核相关
200 的列表托管在其他地方。 200 的列表托管在其他地方。
201 201
202 不要一次发送超过15个补丁到vger邮 202 不要一次发送超过15个补丁到vger邮件列表！！！！
203 203
204 Linus Torvalds是决定改动能否进入 Linu 204 Linus Torvalds是决定改动能否进入 Linux 内核的最终裁决者。他的邮件地址是
205 torvalds@linux-foundation.org 。他收到的 205 torvalds@linux-foundation.org 。他收到的邮件很多，所以一般来说最好 **别**
206 给他发邮件。 206 给他发邮件。
207 207
208 如果您有修复可利用安全漏洞的补 208 如果您有修复可利用安全漏洞的补丁，请将该补丁发送到 security@kernel.org 。对于
209 严重的bug，可以考虑短期禁令以允 209 严重的bug，可以考虑短期禁令以允许分销商（有时间）向用户发布补丁；在这种情况下，
210 显然不应将补丁发送到任何公共列 210 显然不应将补丁发送到任何公共列表。
211 参见 Documentation/translations/zh_CN/proces !! 211 参见 Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。
212 212
213 修复已发布内核中严重错误的补丁 213 修复已发布内核中严重错误的补丁程序应该抄送给稳定版维护人员，方法是把以下列行
214 放进补丁的签准区（注意，不是电 214 放进补丁的签准区（注意，不是电子邮件收件人）::
215 215
216 Cc: stable@vger.kernel.org 216 Cc: stable@vger.kernel.org
217 217
218 除了本文件之外，您还应该阅读 218 除了本文件之外，您还应该阅读
219 Documentation/translations/zh_CN/process/stabl 219 Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。
220 220
221 如果更改影响到用户侧内核接口， 221 如果更改影响到用户侧内核接口，请向手册页维护人员（如维护人员文件中所列）发送
222 手册页补丁，或至少发送更改通知 222 手册页补丁，或至少发送更改通知，以便一些信息进入手册页。还应将用户空间API
223 更改抄送到 linux-api@vger.kernel.org 。 223 更改抄送到 linux-api@vger.kernel.org 。
224 224
225 225
226 不要MIME编码，不要链接，不要压缩 226 不要MIME编码，不要链接，不要压缩，不要附件，只要纯文本
227 ---------------------------------------------- 227 ------------------------------------------------------
228 228
229 Linus 和其他的内核开发者需要阅读 229 Linus 和其他的内核开发者需要阅读和评论你提交的改动。对于内核开发者来说
230 ，可以“引用”你的改动很重要， 230 ，可以“引用”你的改动很重要，使用一般的邮件工具，他们就可以在你的
231 代码的任何位置添加评论。 231 代码的任何位置添加评论。
232 232
233 因为这个原因，所有的提交的补丁 233 因为这个原因，所有的提交的补丁都是邮件中“内嵌”的。最简单（和推荐）的方法就
234 是使用 ``git send-email`` 。https://git-se 234 是使用 ``git send-email`` 。https://git-send-email.io 有 ``git send-email``
235 的交互式教程。 235 的交互式教程。
236 236
237 如果你选择不用 ``git send-email`` ： 237 如果你选择不用 ``git send-email`` ：
238 238
239 .. warning:: 239 .. warning::
240 240
241 如果你使用剪切-粘贴你的补丁， 241 如果你使用剪切-粘贴你的补丁，小心你的编辑器的自动换行功能破坏你的补丁
242 242
243 不要将补丁作为MIME编码的附件，不 243 不要将补丁作为MIME编码的附件，不管是否压缩。很多流行的邮件软件不
244 是任何时候都将MIME编码的附件当作 244 是任何时候都将MIME编码的附件当作纯文本发送的，这会使得别人无法在你的
245 代码中加评论。另外，MIME编码的附 245 代码中加评论。另外，MIME编码的附件会让Linus多花一点时间来处理，这就
246 降低了你的改动被接受的可能性。 246 降低了你的改动被接受的可能性。
247 247
248 例外：如果你的邮路损坏了补丁， 248 例外：如果你的邮路损坏了补丁，那么有人可能会要求你使用MIME重新发送补丁。
249 249
250 请参阅 Documentation/translations/zh_CN/pro 250 请参阅 Documentation/translations/zh_CN/process/email-clients.rst
251 以获取有关配置电子邮件客户端以 251 以获取有关配置电子邮件客户端以使其不受影响地发送补丁的提示。
252 252
253 回复审阅意见 253 回复审阅意见
254 ------------ 254 ------------
255 255
256 你的补丁几乎肯定会得到审阅者对 256 你的补丁几乎肯定会得到审阅者对补丁改进方法的评论（以回复邮件的形式）。您必须
257 对这些评论作出回应；让补丁被忽 257 对这些评论作出回应；让补丁被忽略的一个好办法就是忽略审阅者的意见。直接回复邮
258 件来回应意见即可。不会导致代码 258 件来回应意见即可。不会导致代码更改的意见或问题几乎肯定会带来注释或变更日志的
259 改变，以便下一个审阅者更好地了 259 改变，以便下一个审阅者更好地了解正在发生的事情。
260 260
261 一定要告诉审阅者你在做什么改变 261 一定要告诉审阅者你在做什么改变，并感谢他们的时间。代码审阅是一个累人且耗时的
262 过程，审阅者有时会变得暴躁。即 262 过程，审阅者有时会变得暴躁。即使在这种情况下，也要礼貌地回应并解决他们指出的
263 问题。当发送下一版时，在封面邮 263 问题。当发送下一版时，在封面邮件或独立补丁里加上 ``patch changelog`` 说明与
264 前一版本的不同之处（参见 :ref:`zh_ 264 前一版本的不同之处（参见 :ref:`zh_the_canonical_patch_format` ）。
265 265
266 .. _zh_resend_reminders: 266 .. _zh_resend_reminders:
267 267
268 不要泄气或不耐烦 268 不要泄气或不耐烦
269 ---------------- 269 ----------------
270 270
271 提交更改后，请耐心等待。审阅者 271 提交更改后，请耐心等待。审阅者是大忙人，可能无法立即审阅您的补丁。
272 272
273 曾几何时，补丁曾在没收到评论的 273 曾几何时，补丁曾在没收到评论的情况下消失在虚空中，但现在开发过程应该更加顺利了。
274 您应该在一周左右的时间内收到评 274 您应该在一周左右的时间内收到评论；如果没有收到评论，请确保您已将补丁发送
275 到正确的位置。在重新提交或联系 275 到正确的位置。在重新提交或联系审阅者之前至少等待一周——在诸如合并窗口之类的
276 繁忙时间可能更长。 276 繁忙时间可能更长。
277 277
278 在等了几个星期后，用带RESEND的主 278 在等了几个星期后，用带RESEND的主题重发补丁也是可以的::
279 279
280 [PATCH Vx RESEND] sub/sys: Condensed patch 280 [PATCH Vx RESEND] sub/sys: Condensed patch summary
281 281
282 当你发布补丁（系列）修改版的时 282 当你发布补丁（系列）修改版的时候，不要加上“RESEND”——“RESEND”只适用于重
283 新提交之前未经修改的补丁（系列 283 新提交之前未经修改的补丁（系列）。
284 284
285 主题中包含 PATCH 285 主题中包含 PATCH
286 ---------------- 286 ----------------
287 287
288 由于到Linus和linux-kernel的电子邮件 288 由于到Linus和linux-kernel的电子邮件流量很高，通常会在主题行前面加上[PATCH]
289 前缀。这使Linus和其他内核开发人 289 前缀。这使Linus和其他内核开发人员更容易将补丁与其他电子邮件讨论区分开。
290 290
291 ``git send-email`` 会自动为你加上。 291 ``git send-email`` 会自动为你加上。
292 292
293 签署你的作品——开发者来源认证 293 签署你的作品——开发者来源认证
294 ------------------------------ 294 ------------------------------
295 295
296 为了加强对谁做了何事的追踪，尤 296 为了加强对谁做了何事的追踪，尤其是对那些透过好几层维护者才最终到达的补丁，我
297 们在通过邮件发送的补丁上引入了 297 们在通过邮件发送的补丁上引入了“签署（sign-off）”流程。
298 298
299 “签署”是在补丁注释最后的一行 299 “签署”是在补丁注释最后的一行简单文字，认证你编写了它或者其他
300 人有权力将它作为开放源代码的补 300 人有权力将它作为开放源代码的补丁传递。规则很简单：如果你能认证如下信息:
301 301
302 开发者来源认证 1.1 302 开发者来源认证 1.1
303 ^^^^^^^^^^^^^^^^^^ 303 ^^^^^^^^^^^^^^^^^^
304 304
305 对于本项目的贡献，我认证如下信 305 对于本项目的贡献，我认证如下信息：
306 306
307 (a) 这些贡献是完全或者部分 307 (a) 这些贡献是完全或者部分的由我创建，我有权利以文件中指出
308 的开放源代码许可证提交 308 的开放源代码许可证提交它；或者
309 309
310 (b) 这些贡献基于以前的工作 310 (b) 这些贡献基于以前的工作，据我所知，这些以前的工作受恰当的开放
311 源代码许可证保护，而且 311 源代码许可证保护，而且，根据文件中指出的许可证，我有权提交修改后的贡献，
312 无论是完全还是部分由我 312 无论是完全还是部分由我创造，这些贡献都使用同一个开放源代码许可证
313 （除非我被允许用其它的 313 （除非我被允许用其它的许可证）；或者
314 314
315 (c) 这些贡献由认证（a），（b 315 (c) 这些贡献由认证（a），（b）或者（c）的人直接提供给我，而
316 且我没有修改它。 316 且我没有修改它。
317 317
318 (d) 我理解并同意这个项目和 318 (d) 我理解并同意这个项目和贡献是公开的，贡献的记录（包括我
319 一起提交的个人记录，包 319 一起提交的个人记录，包括sign-off）被永久维护并且可以和这个项目
320 或者开放源代码的许可证 320 或者开放源代码的许可证同步地再发行。
321 321
322 那么加入这样一行:: 322 那么加入这样一行::
323 323
324 Signed-off-by: Random J Developer <random@dev 324 Signed-off-by: Random J Developer <random@developer.example.org>
325 325
326 使用你的真名（抱歉，不能使用假 326 使用你的真名（抱歉，不能使用假名或者匿名。）如果使用 ``git commit -s`` 的话
327 将会自动完成。撤销也应当包含“S 327 将会自动完成。撤销也应当包含“Signed-off-by”， ``git revert -s`` 会帮你搞定。
328 328
329 有些人会在最后加上额外的标签。 329 有些人会在最后加上额外的标签。现在这些东西会被忽略，但是你可以这样做，来标记
330 公司内部的过程，或者只是指出关 330 公司内部的过程，或者只是指出关于签署的一些特殊细节。
331 331
332 作者签署之后的任何其他签署（Sign 332 作者签署之后的任何其他签署（Signed-off-by:'s）均来自处理和传递补丁的人员，但
333 未参与其开发。签署链应当反映补 333 未参与其开发。签署链应当反映补丁传播到维护者并最终传播到Linus所经过的 **真实**
334 路径，首个签署指明单个作者的主 334 路径，首个签署指明单个作者的主要作者身份。
335 335
336 何时使用Acked-by:，Cc:，和Co-developed- !! 336 何时使用Acked-by:，CC:，和Co-Developed by:
337 ------------------------------------------ 337 ------------------------------------------
338 338
339 Signed-off-by: 标签表示签名者参与了 !! 339 Singed-off-by: 标签表示签名者参与了补丁的开发，或者他/她在补丁的传递路径中。
340 340
341 如果一个人没有直接参与补丁的准 341 如果一个人没有直接参与补丁的准备或处理，但希望表示并记录他们对补丁的批准/赞成，
342 那么他们可以要求在补丁的变更日 342 那么他们可以要求在补丁的变更日志中添加一个Acked-by:。
343 343
344 Acked-by: 通常由受影响代码的维护者 344 Acked-by: 通常由受影响代码的维护者使用，当该维护者既没有贡献也没有转发补丁时。
345 345
346 Acked-by: 不像签署那样正式。这是一 346 Acked-by: 不像签署那样正式。这是一个记录，确认人至少审阅了补丁，并表示接受。
347 因此，补丁合并有时会手动将Acker 347 因此，补丁合并有时会手动将Acker的“Yep，looks good to me”转换为 Acked-By:（但
348 请注意，通常最好要求一个明确的A 348 请注意，通常最好要求一个明确的Ack）。
349 349
350 Acked-by：不一定表示对整个补丁的 350 Acked-by：不一定表示对整个补丁的确认。例如，如果一个补丁影响多个子系统，并且
351 有一个来自某个子系统维护者的Acke 351 有一个来自某个子系统维护者的Acked-By:，那么这通常表示只确认影响维护者代码的部
352 分。这里应该仔细判断。如有疑问 352 分。这里应该仔细判断。如有疑问，应参考邮件列表存档中的原始讨论。
353 353
354 如果某人本应有机会对补丁进行评 354 如果某人本应有机会对补丁进行评论，但没有提供此类评论，您可以选择在补丁中添加
355 ``Cc:`` 这是唯一可以在没有被该人 355 ``Cc:`` 这是唯一可以在没有被该人明确同意的情况下添加的标签——但它应该表明
356 这个人是在补丁上抄送的。此标签 356 这个人是在补丁上抄送的。此标签记录了讨论中包含的潜在利益相关方。
357 357
358 Co-developed-by: 声明补丁是由多个开 358 Co-developed-by: 声明补丁是由多个开发人员共同创建的；当几个人在一个补丁上工
359 作时，它用于给出共同作者（除了F 359 作时，它用于给出共同作者（除了From:所给出的作者之外）。因为Co-developed-by:
360 表示作者身份，所以每个Co-developed- 360 表示作者身份，所以每个Co-developed-by:必须紧跟在相关合作作者的签署之后。标准
361 签署程序要求Signed-off-by:标签的顺 !! 361 签署程序要求Singed-off-by:标签的顺序应尽可能反映补丁的时间历史，无论作者是通
362 过From:还是Co-developed-by:表明。值得 !! 362 过From:还是Co-developed-by:表明。值得注意的是，最后一个Singed-off-by:必须是
363 提交补丁的开发人员。 363 提交补丁的开发人员。
364 364
365 注意，如果From:作者也是电子邮件 365 注意，如果From:作者也是电子邮件标题的From:行中列出的人，则From:标签是可选的。
366 366
367 被From:作者提交的补丁示例:: 367 被From:作者提交的补丁示例::
368 368
369 <changelog> 369 <changelog>
370 370
371 Co-developed-by: First Co-Author <first 371 Co-developed-by: First Co-Author <first@coauthor.example.org>
372 Signed-off-by: First Co-Author <first@c 372 Signed-off-by: First Co-Author <first@coauthor.example.org>
373 Co-developed-by: Second Co-Author <seco 373 Co-developed-by: Second Co-Author <second@coauthor.example.org>
374 Signed-off-by: Second Co-Author <second 374 Signed-off-by: Second Co-Author <second@coauthor.example.org>
375 Signed-off-by: From Author <from@author 375 Signed-off-by: From Author <from@author.example.org>
376 376
377 被合作开发者提交的补丁示例:: 377 被合作开发者提交的补丁示例::
378 378
379 From: From Author <from@author.example. 379 From: From Author <from@author.example.org>
380 380
381 <changelog> 381 <changelog>
382 382
383 Co-developed-by: Random Co-Author <rand 383 Co-developed-by: Random Co-Author <random@coauthor.example.org>
384 Signed-off-by: Random Co-Author <random 384 Signed-off-by: Random Co-Author <random@coauthor.example.org>
385 Signed-off-by: From Author <from@author 385 Signed-off-by: From Author <from@author.example.org>
386 Co-developed-by: Submitting Co-Author < 386 Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
387 Signed-off-by: Submitting Co-Author <su 387 Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
388 388
389 389
390 使用Reported-by:、Tested-by:、Reviewed-by: 390 使用Reported-by:、Tested-by:、Reviewed-by:、Suggested-by:和Fixes:
391 ---------------------------------------------- 391 -----------------------------------------------------------------
392 392
393 Reported-by: 给那些发现错误并报告错 393 Reported-by: 给那些发现错误并报告错误的人致谢，它希望激励他们在将来再次帮助
394 我们。请注意，如果bug是以私有方 394 我们。请注意，如果bug是以私有方式报告的，那么在使用Reported-by标签之前，请
395 先请求许可。此标签是为Bug设计的 395 先请求许可。此标签是为Bug设计的；请不要将其用于感谢功能请求。
396 396
397 Tested-by: 标签表示补丁已由指定的 397 Tested-by: 标签表示补丁已由指定的人（在某些环境中）成功测试。这个标签通知
398 维护人员已经执行了一些测试，为 398 维护人员已经执行了一些测试，为将来的补丁提供了一种定位测试人员的方法，并彰显测试人员的功劳。
399 399
400 Reviewed-by：根据审阅者的监督声明 400 Reviewed-by：根据审阅者的监督声明，表明该补丁已被审阅并被认为是可接受的：
401 401
402 402
403 审阅者的监督声明 403 审阅者的监督声明
404 ^^^^^^^^^^^^^^^^ 404 ^^^^^^^^^^^^^^^^
405 405
406 通过提供我的Reviewed-by:标签，我声 406 通过提供我的Reviewed-by:标签，我声明：
407 407
408 (a) 我已经对这个补丁进行了 408 (a) 我已经对这个补丁进行了一次技术审阅，以评估它是否适合被包含到
409 主线内核中。 409 主线内核中。
410 410
411 (b) 与补丁相关的任何问题、 411 (b) 与补丁相关的任何问题、顾虑或问题都已反馈给提交者。我对提交者对
412 我的评论的回应感到满意 412 我的评论的回应感到满意。
413 413
414 (c) 虽然这一提交可能仍可被 414 (c) 虽然这一提交可能仍可被改进，但我相信，此时，（1）对内核
415 进行了有价值的修改，（2 415 进行了有价值的修改，（2）没有包含争论中涉及的已知问题。
416 416
417 (d) 虽然我已经审阅了补丁并 417 (d) 虽然我已经审阅了补丁并认为它是健全的，但我不会（除非另有明确
418 说明）作出任何保证或担 418 说明）作出任何保证或担保它会在任何给定情况下实现其规定的目的
419 或正常运行。 419 或正常运行。
420 420
421 Reviewed-by是一种观点声明，即补丁 421 Reviewed-by是一种观点声明，即补丁是对内核的适当修改，没有任何遗留的严重技术
422 问题。任何感兴趣的审阅者（完成 422 问题。任何感兴趣的审阅者（完成工作的人）都可以为一个补丁提供一个Reviewed-by
423 标签。此标签用于向审阅者提供致 423 标签。此标签用于向审阅者提供致谢，并通知维护者补丁的审阅进度。
424 当Reviewed-by:标签由已知了解主题区 424 当Reviewed-by:标签由已知了解主题区域并执行彻底检查的审阅者提供时，通常会增加
425 补丁进入内核的可能性。 425 补丁进入内核的可能性。
426 426
427 一旦从测试人员或审阅者的“Tested- 427 一旦从测试人员或审阅者的“Tested-by”和“Reviewed-by”标签出现在邮件列表中，
428 作者应在发送下一个版本时将其添 428 作者应在发送下一个版本时将其添加到适用的补丁中。但是，如果补丁在以下版本中发
429 生了实质性更改，这些标签可能不 429 生了实质性更改，这些标签可能不再适用，因此应该删除。通常，在补丁更改日志中
430 （在 ``---`` 分隔符之后）应该提到 430 （在 ``---`` 分隔符之后）应该提到删除某人的测试者或审阅者标签。
431 431
432 Suggested-by: 表示补丁的想法是由指 432 Suggested-by: 表示补丁的想法是由指定的人提出的，并确保将此想法归功于指定的
433 人。请注意，未经许可，不得添加 433 人。请注意，未经许可，不得添加此标签，特别是如果该想法未在公共论坛上发布。
434 也就是说，如果我们勤快地致谢创 434 也就是说，如果我们勤快地致谢创意提供者，他们将受到鼓舞，很有希望在未来再次
435 帮助我们。 435 帮助我们。
436 436
437 Fixes: 指示补丁修复了之前提交的一 437 Fixes: 指示补丁修复了之前提交的一个问题。它可以便于确定错误的来源，这有助于
438 检查错误修复。这个标签还帮助稳 438 检查错误修复。这个标签还帮助稳定内核团队确定应该接收修复的稳定内核版本。这是
439 指示补丁修复的错误的首选方法。 439 指示补丁修复的错误的首选方法。请参阅 :ref:`zh_describe_changes` 了解更多信息。
440 440
441 .. note:: 441 .. note::
442 442
443 附加Fixes:标签不会改变稳定内核 443 附加Fixes:标签不会改变稳定内核规则流程，也不改变所有稳定版补丁抄送
444 stable@vger.kernel.org的要求。有关更 444 stable@vger.kernel.org的要求。有关更多信息，请阅读
445 Documentation/translations/zh_CN/process/sta 445 Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。
446 446
447 .. _zh_the_canonical_patch_format: 447 .. _zh_the_canonical_patch_format:
448 448
449 标准补丁格式 449 标准补丁格式
450 ------------ 450 ------------
451 451
452 本节描述如何格式化补丁本身。请 452 本节描述如何格式化补丁本身。请注意，如果您的补丁存储在 ``Git`` 存储库中，则
453 可以使用 ``git format-patch`` 进行正确 453 可以使用 ``git format-patch`` 进行正确的补丁格式化。但是，这些工具无法创建
454 必要的文本，因此请务必阅读下面 454 必要的文本，因此请务必阅读下面的说明。
455 455
456 标准的补丁标题行是:: 456 标准的补丁标题行是::
457 457
458 Subject: [PATCH 001/123] 子系统:一句 458 Subject: [PATCH 001/123] 子系统:一句话概述
459 459
460 标准补丁的信体包含如下部分： 460 标准补丁的信体包含如下部分：
461 461
462 - 一个 ``from`` 行指出补丁作者。 462 - 一个 ``from`` 行指出补丁作者。后跟空行（仅当发送补丁的人不是作者时才需要）。
463 463
464 - 说明文字，每行最长75列，这将 464 - 说明文字，每行最长75列，这将被复制到永久变更日志来描述这个补丁。
465 465
466 - 一个空行 466 - 一个空行
467 467
468 - 上述的 ``Signed-off-by:`` 行，也将 468 - 上述的 ``Signed-off-by:`` 行，也将出现在更改日志中。
469 469
470 - 只包含 ``---`` 的标记线。 470 - 只包含 ``---`` 的标记线。
471 471
472 - 任何其他不适合放在变更日志的 472 - 任何其他不适合放在变更日志的注释。
473 473
474 - 实际补丁（ ``diff`` 输出）。 474 - 实际补丁（ ``diff`` 输出）。
475 475
476 标题行的格式，使得对标题行按字 476 标题行的格式，使得对标题行按字母序排序非常的容易——很多邮件客户端都
477 可以支持——因为序列号是用零填 477 可以支持——因为序列号是用零填充的，所以按数字排序和按字母排序是一样的。
478 478
479 邮件标题中的“子系统”标识哪个 479 邮件标题中的“子系统”标识哪个内核子系统将被打补丁。
480 480
481 邮件标题中的“一句话概述”扼要 481 邮件标题中的“一句话概述”扼要的描述邮件中的补丁。“一句话概述”
482 不应该是一个文件名。对于一个补 482 不应该是一个文件名。对于一个补丁系列（“补丁系列”指一系列的多个相关补
483 丁），不要对每个补丁都使用同样 483 丁），不要对每个补丁都使用同样的“一句话概述”。
484 484
485 记住邮件的“一句话概述”会成为 485 记住邮件的“一句话概述”会成为该补丁的全局唯一标识。它会进入 ``git``
486 的改动记录里。然后“一句话概述 486 的改动记录里。然后“一句话概述”会被用在开发者的讨论里，用来指代这个补
487 丁。用户将希望通过搜索引擎搜索 487 丁。用户将希望通过搜索引擎搜索“一句话概述”来找到那些讨论这个补丁的文
488 章。当人们在两三个月后使用诸如 488 章。当人们在两三个月后使用诸如 ``gitk`` 或 ``git log --oneline`` 之类
489 的工具查看数千个补丁时，也会很 489 的工具查看数千个补丁时，也会很快看到它。
490 490
491 出于这些原因，概述必须不超过70-7 491 出于这些原因，概述必须不超过70-75个字符，并且必须描述补丁的更改以及为
492 什么需要补丁。既要简洁又要描述 492 什么需要补丁。既要简洁又要描述性很有挑战性，但写得好的概述应该这样。
493 493
494 概述的前缀可以用方括号括起来： 494 概述的前缀可以用方括号括起来：“Subject: [PATCH <tag>...] <概述>”。标记
495 不被视为概述的一部分，而是描述 495 不被视为概述的一部分，而是描述应该如何处理补丁。如果补丁的多个版本已发
496 送出来以响应评审（即“v1，v2，v3 496 送出来以响应评审（即“v1，v2，v3”）则必须包含版本号，或包含“RFC”以指示
497 评审请求。如果一个补丁系列中有 497 评审请求。如果一个补丁系列中有四个补丁，那么各个补丁可以这样编号：1/4、2/4、
498 3/4、4/4。这可以确保开发人员了解 498 3/4、4/4。这可以确保开发人员了解补丁应用的顺序，且
499 已经查看或应用了补丁系列中的所 499 已经查看或应用了补丁系列中的所有补丁。
500 500
501 一些标题的例子:: 501 一些标题的例子::
502 502
503 Subject: [patch 2/5] ext2: improve scalabi 503 Subject: [patch 2/5] ext2: improve scalability of bitmap searching
504 Subject: [PATCHv2 001/207] x86: fix eflags 504 Subject: [PATCHv2 001/207] x86: fix eflags tracking
505 505
506 ``From`` 行是信体里的最上面一行， 506 ``From`` 行是信体里的最上面一行，具有如下格式::
507 507
508 From: Patch Author <author@example.com> 508 From: Patch Author <author@example.com>
509 509
510 ``From`` 行指明在永久改动日志里， 510 ``From`` 行指明在永久改动日志里，谁会被确认为作者。如果没有 ``From`` 行，那
511 么邮件头里的 ``From:`` 行会被用来 511 么邮件头里的 ``From:`` 行会被用来决定改动日志中的作者。
512 512
513 说明文字将会被提交到永久的源代 513 说明文字将会被提交到永久的源代码改动日志里，因此应针对那些早已经不记得和这
514 个补丁相关的讨论细节的读者。包 514 个补丁相关的讨论细节的读者。包括补丁处理的故障症状（内核日志消息、oops消息
515 等），这对于可能正在搜索提交日 515 等），这对于可能正在搜索提交日志以查找适用补丁的人特别有用。文本应该写得如
516 此详细，以便在数周、数月甚至数 516 此详细，以便在数周、数月甚至数年后阅读时，能够为读者提供所需的细节信息，以
517 掌握创建补丁的 **原因** 。 517 掌握创建补丁的 **原因** 。
518 518
519 如果一个补丁修复了一个编译失败 519 如果一个补丁修复了一个编译失败，那么可能不需要包含 *所有* 编译失败；
520 只要足够让搜索补丁的人能够找到 520 只要足够让搜索补丁的人能够找到它就行了。与概述一样，既要简洁又要描述性。
521 521
522 ``---`` 标记行对于补丁处理工具要 522 ``---`` 标记行对于补丁处理工具要找到哪里是改动日志信息的结束，是不可缺少
523 的。 523 的。
524 524
525 对于 ``---`` 标记之后的额外注解， 525 对于 ``---`` 标记之后的额外注解，一个好的用途就是用来写 ``diffstat`` ，用来显
526 示修改了什么文件和每个文件都增 526 示修改了什么文件和每个文件都增加和删除了多少行。 ``diffstat`` 对于比较大的补
527 丁特别有用。 527 丁特别有用。
528 使用 ``diffstat`` 的选项 ``-p 1 -w 70`` 528 使用 ``diffstat`` 的选项 ``-p 1 -w 70`` 这样文件名就会从内核源代码树的目录开始
529 ，不会占用太宽的空间（很容易适 529 ，不会占用太宽的空间（很容易适合80列的宽度，也许会有一些缩进。）
530 （ ``git`` 默认会生成合适的diffstat 530 （ ``git`` 默认会生成合适的diffstat。）
531 531
532 其余那些只适用于当时或者与维护 532 其余那些只适用于当时或者与维护者相关的注解，不合适放到永久的改动日志里的，也
533 应该放这里。较好的例子就是 ``补 533 应该放这里。较好的例子就是 ``补丁更改记录`` ，记录了v1和v2版本补丁之间的差异。
534 534
535 请将此信息放在将变更日志与补丁 535 请将此信息放在将变更日志与补丁的其余部分分隔开的 ``---`` 行 **之后** 。版本
536 信息不是提交到git树的变更日志的 536 信息不是提交到git树的变更日志的一部分。只是供审阅人员使用的附加信息。如果将
537 其放置在提交标记上方，则需要手 537 其放置在提交标记上方，则需要手动交互才能将其删除。如果它位于分隔线以下，则在
538 应用补丁时会自动剥离:: 538 应用补丁时会自动剥离::
539 539
540 <commit message> 540 <commit message>
541 ... 541 ...
542 Signed-off-by: Author <author@mail> 542 Signed-off-by: Author <author@mail>
543 --- 543 ---
544 V2 -> V3: Removed redundant helper function 544 V2 -> V3: Removed redundant helper function
545 V1 -> V2: Cleaned up coding style and addres 545 V1 -> V2: Cleaned up coding style and addressed review comments
546 546
547 path/to/file | 5+++-- 547 path/to/file | 5+++--
548 ... 548 ...
549 549
550 在后面的参考资料中能看到正确补 550 在后面的参考资料中能看到正确补丁格式的更多细节。
551 551
552 .. _zh_backtraces: 552 .. _zh_backtraces:
553 553
554 提交消息中的回溯（Backtraces） 554 提交消息中的回溯（Backtraces）
555 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 555 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
556 556
557 回溯有助于记录导致问题的调用链 557 回溯有助于记录导致问题的调用链。然而，并非所有回溯都有帮助。例如，早期引导调
558 用链是独特而明显的。而逐字复制 558 用链是独特而明显的。而逐字复制完整的dmesg输出则会增加时间戳、模块列表、寄存
559 器和堆栈转储等分散注意力的信息 559 器和堆栈转储等分散注意力的信息。
560 560
561 因此，最有用的回溯应该从转储中 561 因此，最有用的回溯应该从转储中提取相关信息，以更容易集中在真实问题上。下面是
562 一个剪裁良好的回溯示例:: 562 一个剪裁良好的回溯示例::
563 563
564 unchecked MSR access error: WRMSR to 0xd51 ( 564 unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)
565 at rIP: 0xffffffffae059994 (native_write_msr 565 at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
566 Call Trace: 566 Call Trace:
567 mba_wrmsr 567 mba_wrmsr
568 update_domains 568 update_domains
569 rdtgroup_mkdir 569 rdtgroup_mkdir
570 570
571 .. _zh_explicit_in_reply_to: 571 .. _zh_explicit_in_reply_to:
572 572
573 明确回复邮件头（In-Reply-To） 573 明确回复邮件头（In-Reply-To）
574 ----------------------------- 574 -----------------------------
575 575
576 手动添加回复补丁的的邮件头（In-R 576 手动添加回复补丁的的邮件头（In-Reply_To:）是有用的（例如，使用 ``git send-email`` ），
577 可以将补丁与以前的相关讨论关联 577 可以将补丁与以前的相关讨论关联起来，例如，将bug补丁链接到电子邮件和bug报告。
578 但是，对于多补丁系列，最好避免 578 但是，对于多补丁系列，最好避免在回复时使用链接到该系列的旧版本。这样，
579 补丁的多个版本就不会成为电子邮 579 补丁的多个版本就不会成为电子邮件客户端中无法管理的引用树。如果链接有用，
580 可以使用 https://lore.kernel.org/ 重定 580 可以使用 https://lore.kernel.org/ 重定向器（例如，在封面电子邮件文本中）
581 链接到补丁系列的早期版本。 581 链接到补丁系列的早期版本。
582 582
583 给出基础树信息 583 给出基础树信息
584 -------------- 584 --------------
585 585
586 当其他开发人员收到您的补丁并开 586 当其他开发人员收到您的补丁并开始审阅时，知道应该将您的工作放到代码树历史记录
587 中的什么位置通常很有用。这对于 587 中的什么位置通常很有用。这对于自动化持续集成流水（CI）特别有用，这些流水线试
588 图运行一系列测试，以便在维护人 588 图运行一系列测试，以便在维护人员开始审阅之前确定提交的质量。
589 589
590 如果您使用 ``git format-patch`` 生成补 590 如果您使用 ``git format-patch`` 生成补丁，则可以通过 ``--base`` 标志在提交中
591 自动包含基础树信息。使用此选项 591 自动包含基础树信息。使用此选项最简单、最方便的方法是配合主题分支::
592 592
593 $ git checkout -t -b my-topical-branch mas 593 $ git checkout -t -b my-topical-branch master
594 Branch 'my-topical-branch' set up to track 594 Branch 'my-topical-branch' set up to track local branch 'master'.
595 Switched to a new branch 'my-topical-branc 595 Switched to a new branch 'my-topical-branch'
596 596
597 [perform your edits and commits] 597 [perform your edits and commits]
598 598
599 $ git format-patch --base=auto --cover-let 599 $ git format-patch --base=auto --cover-letter -o outgoing/ master
600 outgoing/0000-cover-letter.patch 600 outgoing/0000-cover-letter.patch
601 outgoing/0001-First-Commit.patch 601 outgoing/0001-First-Commit.patch
602 outgoing/... 602 outgoing/...
603 603
604 当你编辑 ``outgoing/0000-cover-letter.patc 604 当你编辑 ``outgoing/0000-cover-letter.patch`` 时，您会注意到在它的最底部有一
605 行 ``base-commit:`` 尾注，它为审阅者 605 行 ``base-commit:`` 尾注，它为审阅者和CI工具提供了足够的信息以正确执行
606 ``git am`` 而不必担心冲突:: 606 ``git am`` 而不必担心冲突::
607 607
608 $ git checkout -b patch-review [base-commi 608 $ git checkout -b patch-review [base-commit-id]
609 Switched to a new branch 'patch-review' 609 Switched to a new branch 'patch-review'
610 $ git am patches.mbox 610 $ git am patches.mbox
611 Applying: First Commit 611 Applying: First Commit
612 Applying: ... 612 Applying: ...
613 613
614 有关此选项的更多信息，请参阅 ``m 614 有关此选项的更多信息，请参阅 ``man git-format-patch`` 。
615 615
616 .. note:: 616 .. note::
617 617
618 ``--base`` 功能是在2.9.0版git中引 618 ``--base`` 功能是在2.9.0版git中引入的。
619 619
620 如果您不使用git格式化补丁，仍然 620 如果您不使用git格式化补丁，仍然可以包含相同的 ``base-commit`` 尾注，以指示您
621 的工作所基于的树的提交哈希。你 621 的工作所基于的树的提交哈希。你应该在封面邮件或系列的第一个补丁中添加它，它应
622 该放在 ``---`` 行的下面或所有其他 622 该放在 ``---`` 行的下面或所有其他内容之后，即只在你的电子邮件签名之前。
623 623
624 参考文献 624 参考文献
625 -------- 625 --------
626 626
627 Andrew Morton，“完美的补丁”（tpp） 627 Andrew Morton，“完美的补丁”（tpp）
628 <https://www.ozlabs.org/~akpm/stuff/tpp.txt> 628 <https://www.ozlabs.org/~akpm/stuff/tpp.txt>
629 629
630 Jeff Garzik，“Linux内核补丁提交格式 630 Jeff Garzik，“Linux内核补丁提交格式”
631 <https://web.archive.org/web/20180829112450/ 631 <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
632 632
633 Greg Kroah-Hartman，“如何惹恼内核子 633 Greg Kroah-Hartman，“如何惹恼内核子系统维护人员”
634 <http://www.kroah.com/log/linux/maintainer.h 634 <http://www.kroah.com/log/linux/maintainer.html>
635 635
636 <http://www.kroah.com/log/linux/maintainer-0 636 <http://www.kroah.com/log/linux/maintainer-02.html>
637 637
638 <http://www.kroah.com/log/linux/maintainer-0 638 <http://www.kroah.com/log/linux/maintainer-03.html>
639 639
640 <http://www.kroah.com/log/linux/maintainer-0 640 <http://www.kroah.com/log/linux/maintainer-04.html>
641 641
642 <http://www.kroah.com/log/linux/maintainer-0 642 <http://www.kroah.com/log/linux/maintainer-05.html>
643 643
644 <http://www.kroah.com/log/linux/maintainer-0 644 <http://www.kroah.com/log/linux/maintainer-06.html>
645 645
646 不！！！别再发巨型补丁炸弹给linu 646 不！！！别再发巨型补丁炸弹给linux-kernel@vger.kernel.org的人们了！
647 <https://lore.kernel.org/r/20050711.125305.08 647 <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net">https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
648 648
649 内核 Documentation/translations/zh_CN/proces 649 内核 Documentation/translations/zh_CN/process/coding-style.rst
650 650
651 Linus Torvalds关于标准补丁格式的邮 651 Linus Torvalds关于标准补丁格式的邮件
652 <https://lore.kernel.org/r/Pine.LNX.4.58.0504 652 <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org">https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>
653 653
654 Andi Kleen，“提交补丁之路” 654 Andi Kleen，“提交补丁之路”
655 一些帮助合入困难或有争议的变 655 一些帮助合入困难或有争议的变更的策略。
656 656
657 http://halobates.de/on-submitting-patches.pd 657 http://halobates.de/on-submitting-patches.pdf
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.