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