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