* [PATCH v3 1/9] docs/zh_CN: Improve zh_CN/process/index.rst
2021-03-05 5:25 [PATCH v3 0/9] docs/zh_CN: Improve language in zh_CN/process/ Wu XiangCheng
@ 2021-03-05 5:26 ` Wu XiangCheng
2021-03-05 5:26 ` [PATCH v3 2/9] docs/zh_CN: Improve zh_CN/process/1.Intro.rst Wu XiangCheng
` (8 subsequent siblings)
9 siblings, 0 replies; 12+ messages in thread
From: Wu XiangCheng @ 2021-03-05 5:26 UTC (permalink / raw)
To: alex.shi; +Cc: corbet, linux-doc
Improve language and grammar of zh_CN/process/index.rst
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
---
Documentation/translations/zh_CN/process/index.rst | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst
index 8051a7b322c5..39e9c88fbaa6 100644
--- a/Documentation/translations/zh_CN/process/index.rst
+++ b/Documentation/translations/zh_CN/process/index.rst
@@ -13,11 +13,11 @@
与Linux 内核社区一起工作
========================
-那么你想成为Linux内核开发人员？ 欢迎！ 不但从技术意义上讲有很多关于内核的知识
-需要学，而且了解我们社区的工作方式也很重要。 阅读这些文章可以让您以更轻松地,
-麻烦最少的方式将更改合并到内核。
+你想成为Linux内核开发人员吗？欢迎之至！在学习许多关于内核的技术知识的同时，
+了解我们社区的工作方式也很重要。阅读这些文档可以让您以更轻松的、麻烦更少的
+方式将更改合并到内核。
-以下是每位开发人员应阅读的基本指南。
+以下是每位开发人员都应阅读的基本指南：
.. toctree::
:maxdepth: 1
@@ -47,7 +47,7 @@
management-style
embargoed-hardware-issues
-这些是一些总体技术指南，由于缺乏更好的地方，现在已经放在这里
+这些是一些总体性技术指南，由于不大好分类而放在这里：
.. toctree::
:maxdepth: 1
--
2.20.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v3 2/9] docs/zh_CN: Improve zh_CN/process/1.Intro.rst
2021-03-05 5:25 [PATCH v3 0/9] docs/zh_CN: Improve language in zh_CN/process/ Wu XiangCheng
2021-03-05 5:26 ` [PATCH v3 1/9] docs/zh_CN: Improve zh_CN/process/index.rst Wu XiangCheng
@ 2021-03-05 5:26 ` Wu XiangCheng
2021-03-05 5:26 ` [PATCH v3 3/9] docs/zh_CN: Improve zh_CN/process/2.Process.rst Wu XiangCheng
` (7 subsequent siblings)
9 siblings, 0 replies; 12+ messages in thread
From: Wu XiangCheng @ 2021-03-05 5:26 UTC (permalink / raw)
To: alex.shi; +Cc: corbet, linux-doc
Improve language and grammar of zh_CN/process/1.Intro.rst
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
---
.../translations/zh_CN/process/1.Intro.rst | 195 +++++++++---------
1 file changed, 102 insertions(+), 93 deletions(-)
diff --git a/Documentation/translations/zh_CN/process/1.Intro.rst b/Documentation/translations/zh_CN/process/1.Intro.rst
index 10a15f3dc282..4f9284cbe33b 100644
--- a/Documentation/translations/zh_CN/process/1.Intro.rst
+++ b/Documentation/translations/zh_CN/process/1.Intro.rst
@@ -1,162 +1,170 @@
.. include:: ../disclaimer-zh_CN.rst
:Original: :ref:`Documentation/process/1.Intro.rst <development_process_intro>`
-:Translator: Alex Shi <alex.shi@linux.alibaba.com>
+
+:Translator:
+
+ 时奎亮 Alex Shi <alex.shi@linux.alibaba.com>
+
+:校译:
+
+ 吴想成 Wu XiangCheng <bobwxc@email.cn>
.. _cn_development_process_intro:
-介绍
+引言
====
-执行摘要
+内容提要
--------
-本节的其余部分涵盖了内核开发过程的范围，以及开发人员及其雇主在这方面可能遇
-到的各种挫折。内核代码应该合并到正式的（“主线”）内核中有很多原因，包括对用
-户的自动可用性、多种形式的社区支持以及影响内核开发方向的能力。提供给Linux
-内核的代码必须在与GPL兼容的许可证下可用。
+本节的其余部分涵盖了内核开发的过程，以及开发人员及其雇主在这方面可能遇到的
+各种问题。有很多原因使内核代码应被合并到正式的（“主线”）内核中，包括对用户
+的自动可用性、多种形式的社区支持以及影响内核开发方向的能力。提供给Linux内核
+的代码必须在与GPL兼容的许可证下可用。
:ref:`cn_development_process` 介绍了开发过程、内核发布周期和合并窗口的机制。
-涵盖了补丁开发、审查和合并周期中的各个阶段。有一些关于工具和邮件列表的讨论。
-鼓励希望开始内核开发的开发人员作为初始练习跟踪并修复bug。
+涵盖了补丁开发、审查和合并周期中的各个阶段。还有一些关于工具和邮件列表的讨论？
+鼓励希望开始内核开发的开发人员跟踪并修复缺陷以作为初步练习。
-:ref:`cn_development_early_stage` 包括早期项目规划，重点是尽快让开发社区参与
+:ref:`cn_development_early_stage` 包括项目的早期规划，重点是尽快让开发社区
+参与进来。
-:ref:`cn_development_coding` 是关于编码过程的；讨论了其他开发人员遇到的几个
-陷阱。对补丁的一些要求已经涵盖，并且介绍了一些工具，这些工具有助于确保内核
+:ref:`cn_development_coding` 是关于编程过程的；介绍了其他开发人员遇到的几个
+陷阱。也涵盖了对补丁的一些要求，并且介绍了一些工具，这些工具有助于确保内核
补丁是正确的。
-:ref:`cn_development_posting` 讨论发布补丁以供评审的过程。为了让开发社区
-认真对待，补丁必须正确格式化和描述，并且必须发送到正确的地方。遵循本节中的
-建议有助于确保为您的工作提供最好的接纳。
+:ref:`cn_development_posting` 描述发布补丁以供评审的过程。为了让开发社区能
+认真对待，补丁必须被正确格式化和描述，并且必须发送到正确的地方。遵循本节中的
+建议有助于确保您的工作能被较好地接纳。
-:ref:`cn_development_followthrough` 介绍了发布补丁之后发生的事情；该工作
-在这一点上还远远没有完成。与审阅者一起工作是开发过程中的一个重要部分；本节
-提供了一些关于如何在这个重要阶段避免问题的提示。当补丁被合并到主线中时，
-开发人员要注意不要假定任务已经完成。
+:ref:`cn_development_followthrough` 介绍了发布补丁之后发生的事情；工作在这时
+还远远没有完成。与审阅者一起工作是开发过程中的一个重要部分；本节提供了一些
+关于如何在这个重要阶段避免问题的提示。当补丁被合并到主线中时，开发人员要注意
+不要假定任务已经完成。
-:ref:`cn_development_advancedtopics` 介绍了两个“高级”主题：
-使用Git管理补丁和查看其他人发布的补丁。
+:ref:`cn_development_advancedtopics` 介绍了两个“高级”主题：使用Git管理补丁
+和查看其他人发布的补丁。
-:ref:`cn_development_conclusion` 总结了有关内核开发的更多信息，附带有带有
-指向资源的链接.
+:ref:`cn_development_conclusion` 总结了有关内核开发的更多信息，附带有相关资源
+链接。
-这个文件是关于什么的
+这个文档是关于什么的
--------------------
-Linux内核有超过800万行代码，每个版本的贡献者超过1000人，是现存最大、最活跃
-的免费软件项目之一。从1991年开始，这个内核已经发展成为一个最好的操作系统
-组件，运行在袖珍数字音乐播放器、台式PC、现存最大的超级计算机以及所有类型的
-系统上。它是一种适用于几乎任何情况的健壮、高效和可扩展的解决方案。
+Linux内核有超过800万行代码，每个版本的贡献者超过1000人，是现存最大、最活跃的
+免费软件项目之一。从1991年开始，这个内核已经发展成为一个最好的操作系统组件，
+运行在袖珍数字音乐播放器、台式电脑、现存最大的超级计算机以及所有类型的系统上。
+它是一种适用于几乎任何情况的健壮、高效和可扩展的解决方案。
随着Linux的发展，希望参与其开发的开发人员（和公司）的数量也在增加。硬件供应商
希望确保Linux能够很好地支持他们的产品，使这些产品对Linux用户具有吸引力。嵌入
式系统供应商使用Linux作为集成产品的组件，希望Linux能够尽可能地胜任手头的任务。
-分销商和其他基于Linux的软件供应商对Linux内核的功能、性能和可靠性有着明确的
-兴趣。最终用户也常常希望修改Linux，使之更好地满足他们的需求。
+分销商和其他基于Linux的软件供应商切实关心Linux内核的功能、性能和可靠性。最终
+用户也常常希望修改Linux，使之能更好地满足他们的需求。
Linux最引人注目的特性之一是这些开发人员可以访问它；任何具备必要技能的人都可以
改进Linux并影响其开发方向。专有产品不能提供这种开放性，这是自由软件的一个特点。
-但是，如果有什么不同的话，内核比大多数其他自由软件项目更开放。一个典型的三个月
-内核开发周期可以涉及1000多个开发人员，他们为100多个不同的公司
-（或者根本没有公司）工作。
+如果有什么不同的话，那就是内核比大多数其他自由软件项目更开放。一个典型的三个
+月内核开发周期可以涉及1000多个开发人员，他们为100多个不同的公司（或者根本不
+隶属公司）工作。
-与内核开发社区合作并不是特别困难。但是，尽管如此，许多潜在的贡献者在尝试做
-内核工作时遇到了困难。内核社区已经发展了自己独特的操作方式，使其能够在每天
+与内核开发社区合作并不是特别困难。但尽管如此，仍有许多潜在的贡献者在尝试做
+内核工作时遇到了困难。内核社区已经发展出自己独特的操作方式，使其能够在每天
都要更改数千行代码的环境中顺利运行（并生成高质量的产品）。因此，Linux内核开发
-过程与专有的开发方法有很大的不同也就不足为奇了。
+过程与专有的开发模式有很大的不同也就不足为奇了。
-对于新开发人员来说，内核的开发过程可能会让人感到奇怪和恐惧，但这个背后有充分的
-理由和坚实的经验。一个不了解内核社区的方式的开发人员（或者更糟的是，他们试图
-抛弃或规避内核社区的方式）会有一个令人沮丧的体验。开发社区, 在帮助那些试图学习
-的人的同时，没有时间帮助那些不愿意倾听或不关心开发过程的人。
+对于新开发人员来说，内核的开发过程可能会让人感到奇怪和恐惧，但这背后有充分的
+理由和坚实的经验。一个不了解内核社区工作方式的开发人员（或者更糟的是，他们
+试图抛弃或规避之）会得到令人沮丧的体验。开发社区在帮助那些试图学习的人的同时，
+没有时间帮助那些不愿意倾听或不关心开发过程的人。
-希望阅读本文的人能够避免这种令人沮丧的经历。这里有很多材料，但阅读时所做的
+希望阅读本文的人能够避免这种令人沮丧的经历。这些材料很长，但阅读它们时所做的
努力会在短时间内得到回报。开发社区总是需要能让内核变更好的开发人员；下面的
-文本应该帮助您或为您工作的人员加入我们的社区。
+文字应该帮助您或为您工作的人员加入我们的社区。
致谢
----
-本文件由Jonathan Corbet撰写，corbet@lwn.net。以下人员的建议使之更为完善：
+本文档由Jonathan Corbet <corbet@lwn.net> 撰写。以下人员的建议使之更为完善：
Johannes Berg, James Berry, Alex Chiang, Roland Dreier, Randy Dunlap,
Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, Amanda McPherson,
-Andrew Morton, Andrew Price, Tsugikazu Shibata, 和 Jochen Voß.
+Andrew Morton, Andrew Price, Tsugikazu Shibata 和 Jochen Voß 。
这项工作得到了Linux基金会的支持，特别感谢Amanda McPherson，他看到了这项工作
-的价值并把它变成现实。
+的价值并将其变成现实。
代码进入主线的重要性
--------------------
有些公司和开发人员偶尔会想，为什么他们要费心学习如何与内核社区合作，并将代码
放入主线内核（“主线”是由Linus Torvalds维护的内核，Linux发行商将其用作基础）。
-在短期内，贡献代码看起来像是一种可以避免的开销；仅仅将代码分开并直接支持用户
+在短期内，贡献代码看起来像是一种可以避免的开销；维护独立代码并直接支持用户
似乎更容易。事实上，保持代码独立（“树外”）是在经济上是错误的。
-作为说明树外代码成本的一种方法，下面是内核开发过程的一些相关方面；本文稍后将
-更详细地讨论其中的大部分内容。考虑：
+为了说明树外代码成本，下面给出内核开发过程的一些相关方面；本文稍后将更详细地
+讨论其中的大部分内容。请考虑：
- 所有Linux用户都可以使用合并到主线内核中的代码。它将自动出现在所有启用它的
- 发行版上。不需要驱动程序磁盘、下载，也不需要为多个发行版的多个版本提供支持；
- 对于开发人员和用户来说，这一切都是可行的。并入主线解决了大量的分布和支持问题
+ 发行版上。无需驱动程序磁盘、额外下载，也不需要为多个发行版的多个版本提供
+ 支持；这一切将方便所有开发人员和用户。并入主线解决了大量的分发和支持问题。
-- 当内核开发人员努力维护一个稳定的用户空间接口时，内部内核API处于不断变化之中.
- 缺乏一个稳定的内部接口是一个深思熟虑的设计决策；它允许在任何时候进行基本的改
- 进，并产生更高质量的代码。但该策略的一个结果是，如果要使用新的内核，任何树外
- 代码都需要持续的维护。维护树外代码需要大量的工作才能使代码保持工作状态。
+- 当内核开发人员努力维护一个稳定的用户空间接口时，内核内部API处于不断变化之中。
+ 不维持稳定的内部接口是一个慎重的设计决策；它允许在任何时候进行基本的改进，
+ 并产出更高质量的代码。但该策略导致结果是，若要使用新的内核，任何树外代码都
+ 需要持续的维护。维护树外代码会需要大量的工作才能使代码保持正常运行。
- 相反，位于主线中的代码不需要这样做，因为一个简单的规则要求进行API更改的任何
- 开发人员也必须修复由于该更改而破坏的任何代码。因此，合并到主线中的代码大大
- 降低了维护成本。
+ 相反，位于主线中的代码不需要这样做，因为基本规则要求进行API更改的任何开发
+ 人员也必须修复由于该更改而破坏的任何代码。因此，合并到主线中的代码大大降低
+ 了维护成本。
-- 除此之外，内核中的代码通常会被其他开发人员改进。令人惊讶的结果可能来自授权
- 您的用户社区和客户改进您的产品。
+- 除此之外，内核中的代码通常会被其他开发人员改进。您授权的用户社区和客户对您
+ 产品的改进可能会令人惊喜。
-- 内核代码在合并到主线之前和之后都要经过审查。不管原始开发人员的技能有多强，
+- 内核代码在合并到主线之前和之后都要经过审查。无论原始开发人员的技能有多强，
这个审查过程总是能找到改进代码的方法。审查经常发现严重的错误和安全问题。
- 这对于在封闭环境中开发的代码尤其如此；这种代码从外部开发人员的审查中获益
- 匪浅。树外代码是低质量代码。
+ 对于在封闭环境中开发的代码尤其如此；这种代码从外部开发人员的审查中获益匪浅。
+ 树外代码是低质量代码。
- 参与开发过程是您影响内核开发方向的方式。旁观者的抱怨会被听到，但是活跃的
开发人员有更强的声音——并且能够实现使内核更好地满足其需求的更改。
- 当单独维护代码时，总是存在第三方为类似功能提供不同实现的可能性。如果发生
- 这种情况，合并代码将变得更加困难——甚至到了不可能的地步。然后，您将面临以下
- 令人不快的选择：（1）无限期地维护树外的非标准特性，或（2）放弃代码并将用户
- 迁移到树内版本。
+ 这种情况，合并代码将变得更加困难——甚至成为不可能。之后，您将面临以下令人
+ 不快的选择：（1）无限期地维护树外的非标准特性，或（2）放弃代码并将用户迁移
+ 到树内版本。
-- 代码的贡献是使整个过程工作的根本。通过贡献代码，您可以向内核添加新功能，并
- 提供其他内核开发人员使用的功能和示例。如果您已经为Linux开发了代码（或者
- 正在考虑这样做），那么您显然对这个平台的持续成功感兴趣；贡献代码是确保成功
- 的最好方法之一。
+- 代码的贡献是使整个流程工作的根本。通过贡献代码，您可以向内核添加新功能，并
+ 提供其他内核开发人员使用的功能和示例。如果您已经为Linux开发了代码（或者正在
+ 考虑这样做），那么您显然对这个平台的持续成功感兴趣；贡献代码是确保成功的
+ 最好方法之一。
上述所有理由都适用于任何树外内核代码，包括以专有的、仅二进制形式分发的代码。
-然而，在考虑任何类型的纯二进制内核代码分布之前，还需要考虑其他因素。这些包括：
+然而，在考虑任何类型的纯二进制内核代码分布之前，还需要考虑其他因素。包括：
-- 围绕专有内核模块分发的法律问题充其量是模糊的；相当多的内核版权所有者认为，
- 大多数仅限二进制的模块是内核的派生产品，因此，它们的分发违反了GNU通用公共
- 许可证（下面将详细介绍）。您的作者不是律师，本文档中的任何内容都不可能被
+- 围绕专有内核模块分发的法律问题其实较为模糊；相当多的内核版权所有者认为，
+ 大多数仅二进制的模块是内核的派生产品，因此，它们的分发违反了GNU通用公共
+ 许可证（下面将详细介绍）。本文作者不是律师，本文档中的任何内容都不可能被
视为法律建议。封闭源代码模块的真实法律地位只能由法院决定。但不管怎样，困扰
这些模块的不确定性仍然存在。
- 二进制模块大大增加了调试内核问题的难度，以至于大多数内核开发人员甚至都不会
尝试。因此，只分发二进制模块将使您的用户更难从社区获得支持。
-- 对于只支持二进制的模块的发行者来说，支持也更加困难，他们必须为他们希望支持
- 的每个发行版和每个内核版本提供一个版本的模块。为了提供相当全面的覆盖范围，
+- 对于仅二进制的模块的发行者来说，支持也更加困难，他们必须为他们希望支持的
+ 每个发行版和每个内核版本提供不同版本的模块。为了提供较为全面的覆盖范围，
可能需要一个模块的几十个构建，并且每次升级内核时，您的用户都必须单独升级
- 您的模块。
+ 这些模块。
-- 上面提到的关于代码评审的所有问题都更加存在于封闭源代码。由于该代码根本不可
- 用，因此社区无法对其进行审查，毫无疑问，它将存在严重问题。
+- 上面提到的关于代码评审的所有问题都更加存在于封闭源代码中。由于该代码根本
+ 不可得，因此社区无法对其进行审查，毫无疑问，它将存在严重问题。
-尤其是嵌入式系统的制造商，可能会倾向于忽视本节中所说的大部分内容，因为他们
+尤其是嵌入式系统的制造商，可能会倾向于忽视本节中所说的大部分内容；因为他们
相信自己正在商用一种使用冻结内核版本的独立产品，在发布后不需要再进行开发。
这个论点忽略了广泛的代码审查的价值以及允许用户向产品添加功能的价值。但这些
-产品也有有限的商业寿命，之后必须发布新版本的产品。在这一点上，代码在主线上
-并得到良好维护的供应商将能够更好地占位，以使新产品快速上市。
+产品的商业寿命有限，之后必须发布新版本的产品。在这一点上，代码在主线上并得到
+良好维护的供应商将能够更好地占位，以使新产品快速上市。
许可
----
@@ -164,23 +172,24 @@ Andrew Morton, Andrew Price, Tsugikazu Shibata, 和 Jochen Voß.
代码是根据一些许可证提供给Linux内核的，但是所有代码都必须与GNU通用公共许可
证（GPLV2）的版本2兼容，该版本是覆盖整个内核分发的许可证。在实践中，这意味
着所有代码贡献都由GPLv2（可选地，语言允许在更高版本的GPL下分发）或3子句BSD
-许可（New BSD License, 译者注）覆盖。任何不包含在兼容许可证中的贡献都不会
+许可（New BSD License，译者注）覆盖。任何不包含在兼容许可证中的贡献都不会
被接受到内核中。
贡献给内核的代码不需要（或请求）版权分配。合并到主线内核中的所有代码都保留
其原始所有权；因此，内核现在拥有数千个所有者。
-这种所有权结构的一个暗示是，任何改变内核许可的尝试都注定会失败。很少有实际
-的场景可以获得所有版权所有者的同意（或者从内核中删除他们的代码）。因此，特
-别是，在可预见的将来，不可能迁移到GPL的版本3。
+这种所有权结构也暗示着，任何改变内核许可的尝试都注定会失败。很少有实际情况
+可以获得所有版权所有者的同意（或者从内核中删除他们的代码）。因此，尤其是在
+可预见的将来，许可证不大可能迁移到GPL的版本3。
-所有贡献给内核的代码都必须是合法的免费软件。因此，不接受匿名（或匿名）贡献
-者的代码。所有贡献者都需要在他们的代码上“sign off”，声明代码可以在GPL下与内
-核一起分发。无法提供未被其所有者许可为免费软件的代码，或可能为内核造成版权
-相关问题的代码（例如，由缺乏适当保护的反向工程工作派生的代码）不能被接受。
+所有贡献给内核的代码都必须是合法的免费软件。因此，不接受匿名（或化名）贡献
+者的代码。所有贡献者都需要在他们的代码上“sign off（签发）”，声明代码可以
+在GPL下与内核一起分发。无法提供未被其所有者许可为免费软件的代码，或可能为
+内核造成版权相关问题的代码（例如，由缺乏适当保护的反向工程工作派生的代码）
+不能被接受。
-有关版权相关问题的问题在Linux开发邮件列表中很常见。这样的问题通常会得到不少
-答案，但要记住，回答这些问题的人不是律师，不能提供法律咨询。如果您有关于
-Linux源代码的法律问题，那么与了解该领域的律师交流是无法替代的。依靠从技术
-邮件列表中获得的答案是一件冒险的事情。
+有关版权问题的提问在Linux开发邮件列表中很常见。这样的问题通常会得到不少答案，
+但请记住，回答这些问题的人不是律师，不能提供法律咨询。如果您有关于Linux源代码
+的法律问题，没有什么可以代替咨询了解这一领域的律师。依赖从技术邮件列表中获得
+的答案是一件冒险的事情。
--
2.20.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v3 3/9] docs/zh_CN: Improve zh_CN/process/2.Process.rst
2021-03-05 5:25 [PATCH v3 0/9] docs/zh_CN: Improve language in zh_CN/process/ Wu XiangCheng
2021-03-05 5:26 ` [PATCH v3 1/9] docs/zh_CN: Improve zh_CN/process/index.rst Wu XiangCheng
2021-03-05 5:26 ` [PATCH v3 2/9] docs/zh_CN: Improve zh_CN/process/1.Intro.rst Wu XiangCheng
@ 2021-03-05 5:26 ` Wu XiangCheng
2021-03-05 5:27 ` [PATCH v3 4/9] docs/zh_CN: Improve zh_CN/process/3.Early-stage.rst Wu XiangCheng
` (6 subsequent siblings)
9 siblings, 0 replies; 12+ messages in thread
From: Wu XiangCheng @ 2021-03-05 5:26 UTC (permalink / raw)
To: alex.shi; +Cc: corbet, linux-doc
Sync and improve language & grammar of zh_CN/process/2.Process.rst
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
---
.../translations/zh_CN/process/2.Process.rst | 345 +++++++++---------
1 file changed, 175 insertions(+), 170 deletions(-)
diff --git a/Documentation/translations/zh_CN/process/2.Process.rst b/Documentation/translations/zh_CN/process/2.Process.rst
index ebe2e0254b3e..229629e305ca 100644
--- a/Documentation/translations/zh_CN/process/2.Process.rst
+++ b/Documentation/translations/zh_CN/process/2.Process.rst
@@ -1,17 +1,24 @@
.. include:: ../disclaimer-zh_CN.rst
:Original: :ref:`Documentation/process/2.Process.rst <development_process>`
-:Translator: Alex Shi <alex.shi@linux.alibaba.com>
+
+:Translator:
+
+ 时奎亮 Alex Shi <alex.shi@linux.alibaba.com>
+
+:校译:
+
+ 吴想成 Wu XiangCheng <bobwxc@email.cn>
.. _cn_development_process:
-开发流程如何工作
+开发流程如何进行
================
-90年代早期的Linux内核开发是一件相当松散的事情，涉及的用户和开发人员相对较
-少。由于拥有数以百万计的用户群，并且在一年的时间里有大约2000名开发人员参与
-进来，内核因此必须发展许多流程来保持开发的顺利进行。要成为流程的有效组成
-部分，需要对流程的工作方式有一个扎实的理解。
+90年代早期的Linux内核开发是一件相当松散的事情，涉及的用户和开发人员相对较少。
+由于拥有数以百万计的用户群，且每年有大约2000名开发人员参与进来，内核因此必须
+发展出许多既定流程来保证开发的顺利进行。要参与到流程中来，需要对此流程的进行
+方式有一个扎实的理解。
总览
----
@@ -20,112 +27,113 @@
内核版本。最近的发布历史记录如下：
====== =================
- 4.11 四月 30, 2017
- 4.12 七月 2, 2017
- 4.13 九月 3, 2017
- 4.14 十一月 12, 2017
- 4.15 一月 28, 2018
- 4.16 四月 1, 2018
+ 5.0 2019年3月3日
+ 5.1 2019年5月5日
+ 5.2 2019年7月7日
+ 5.3 2019年9月15日
+ 5.4 2019年11月24日
+ 5.5 2020年1月6日
====== =================
-每4.x版本都是一个主要的内核版本，具有新特性、内部API更改等等。一个典型的4.x
-版本包含大约13000个变更集，变更了几十万行代码。因此，4.x是Linux内核开发的前
+每个5.x版本都是一个主要的内核版本，具有新特性、内部API更改等等。一个典型的5.x
+版本包含大约13000个变更集，变更了几十万行代码。因此，5.x是Linux内核开发的前
沿；内核使用滚动开发模型，不断集成重大变化。
-对于每个版本的补丁合并，遵循一个相对简单的规则。在每个开发周期的开始，“合并
-窗口”被打开。当时，被认为足够稳定（并且被开发社区接受）的代码被合并到主线内
+对于每个版本的补丁合并，遵循一个相对简单的规则。在每个开发周期的开头，“合并
+窗口”被打开。这时，被认为足够稳定（并且被开发社区接受）的代码被合并到主线内
核中。在这段时间内，新开发周期的大部分变更（以及所有主要变更）将以接近每天
1000次变更（“补丁”或“变更集”）的速度合并。
-（顺便说一句，值得注意的是，合并窗口期间集成的更改并不是凭空产生的；它们是
-提前收集、测试和分级的。稍后将详细描述该过程的工作方式）。
+（顺便说一句，值得注意的是，合并窗口期间集成的更改并不是凭空产生的；它们是经
+提前收集、测试和分级的。稍后将详细描述该过程的工作方式。）
合并窗口持续大约两周。在这段时间结束时，LinusTorvalds将声明窗口已关闭，并
-释放第一个“rc”内核。例如，对于目标为4.14的内核，在合并窗口结束时发生的释放
-将被称为4.14-rc1。RC1版本是一个信号，表示合并新特性的时间已经过去，稳定下一
-个内核的时间已经开始。
+释放第一个“rc”内核。例如，对于目标为5.6的内核，在合并窗口结束时发生的释放
+将被称为5.6-rc1。-rc1 版本是一个信号，表示合并新特性的时间已经过去，稳定下一
+个内核的时间已经到来。
在接下来的6到10周内，只有修复问题的补丁才应该提交给主线。有时会允许更大的
-更改，但这种情况很少发生；试图在合并窗口外合并新功能的开发人员往往会受到不
+更改，但这种情况很少发生；试图在合并窗口外合并新功能的开发人员往往受不到
友好的接待。一般来说，如果您错过了给定特性的合并窗口，最好的做法是等待下一
-个开发周期。（对于以前不支持的硬件，偶尔会对驱动程序进行例外；如果它们不
-改变已有代码，则不会导致回归，并且应该可以随时安全地添加）。
+个开发周期。（偶尔会对未支持硬件的驱动程序进行例外；如果它们不改变已有代码，
+则不会导致回归，应该可以随时被安全地加入）。
随着修复程序进入主线，补丁速度将随着时间的推移而变慢。Linus大约每周发布一次
-新的-rc内核；一个正常的系列将在-rc6和-rc9之间，内核被认为足够稳定并最终发布。
+新的-rc内核；在内核被认为足够稳定并最终发布前，一般会达到-rc6到-rc9之间。
然后，整个过程又重新开始了。
-例如，这里是4.16的开发周期进行情况（2018年的所有日期）:
+例如，这里是5.4的开发周期进行情况（2019年）:
============== ==============================
- 一月 28 4.15 稳定版发布
- 二月 11 4.16-rc1, 合并窗口关闭
- 二月 18 4.16-rc2
- 二月 25 4.16-rc3
- 三月 4 4.16-rc4
- 三月 11 4.16-rc5
- 三月 18 4.16-rc6
- 三月 25 4.16-rc7
- 四月 1 4.16 稳定版发布
+ 九月 15 5.3 稳定版发布
+ 九月 30 5.4-rc1 合并窗口关闭
+ 十月 6 5.4-rc2
+ 十月 13 5.4-rc3
+ 十月 20 5.4-rc4
+ 十月 27 5.4-rc5
+ 十一月 3 5.4-rc6
+ 十一月 10 5.4-rc7
+ 十一月 17 5.4-rc8
+ 十一月 24 5.4 稳定版发布
============== ==============================
-开发人员如何决定何时结束开发周期并创建稳定的版本？使用的最重要的指标是以前
-版本的回归列表。不欢迎出现任何错误，但是那些破坏了以前能工作的系统的错误被
-认为是特别严重的。因此，导致回归的补丁是不受欢迎的，很可能在稳定期内删除。
+开发人员如何决定何时结束开发周期并创建稳定版本？最重要的指标是以前版本的
+回归列表。不欢迎出现任何错误，但是那些破坏了以前能工作的系统的错误被认为是
+特别严重的。因此，导致回归的补丁是不受欢迎的，很可能在稳定期内删除。
开发人员的目标是在稳定发布之前修复所有已知的回归。在现实世界中，这种完美是
-很难实现的；在这种规模的项目中，变量太多了。有一点，延迟最终版本只会使问题
-变得更糟；等待下一个合并窗口的一堆更改将变大，从而在下次创建更多的回归错误。
-因此，大多数4.x内核都有一些已知的回归错误，不过，希望没有一个是严重的。
+很难实现的；在这种规模的项目中，变数太多了。需要说明的是，延迟最终版本只会
+使问题变得更糟；等待下一个合并窗口的更改将变多，导致下次出现更多的回归错误。
+因此，大多数5.x内核都有一些已知的回归错误，不过，希望没有一个是严重的。
-一旦一个稳定的版本发布，它正在进行的维护工作就被移交给“稳定团队”，目前由
-Greg Kroah-Hartman组成。稳定团队将使用4.x.y编号方案不定期的发布稳定版本的更
-新。要加入更新版本，补丁程序必须（1）修复一个重要的bug，（2）已经合并到
-下一个开发主线中。内核通常会在超过其初始版本的一个以上的开发周期内接收稳定
-的更新。例如，4.13内核的历史如下
+一旦一个稳定的版本发布，它的持续维护工作就被移交给“稳定团队”，目前由
+Greg Kroah-Hartman领导。稳定团队将使用5.x.y编号方案不定期地发布稳定版本的
+更新。要合入更新版本，补丁必须（1）修复一个重要的缺陷，且（2）已经合并到
+下一个开发版本主线中。内核通常会在其初始版本后的一个以上的开发周期内收到
+稳定版更新。例如，5.2内核的历史如下（2019年）：
============== ===============================
- 九月 3 4.13 稳定版发布
- 九月 13 4.13.1
- 九月 20 4.13.2
- 九月 27 4.13.3
- 十月 5 4.13.4
- 十月 12 4.13.5
+ 七月 7 5.2 稳定版发布
+ 七月 13 5.2.1
+ 七月 21 5.2.2
+ 七月 26 5.2.3
+ 七月 28 5.2.4
+ 七月 31 5.2.5
... ...
- 十一月 24 4.13.16
+ 十月 11 5.2.21
============== ===============================
-4.13.16是4.13版本的最终稳定更新。
+5.2.21是5.2版本的最终稳定更新。
有些内核被指定为“长期”内核；它们将得到更长时间的支持。在本文中，当前的长期
内核及其维护者是：
- ====== ====================== ==============================
- 3.16 Ben Hutchings (长期稳定内核)
- 4.1 Sasha Levin
- 4.4 Greg Kroah-Hartman (长期稳定内核)
- 4.9 Greg Kroah-Hartman
- 4.14 Greg Kroah-Hartman
- ====== ====================== ==============================
+ ====== ================================ ================
+ 3.16 Ben Hutchings （长期稳定内核）
+ 4.4 Greg Kroah-Hartman & Sasha Levin （长期稳定内核）
+ 4.9 Greg Kroah-Hartman & Sasha Levin
+ 4.14 Greg Kroah-Hartman & Sasha Levin
+ 4.19 Greg Kroah-Hartman & Sasha Levin
+ 5.4 Greg Kroah-Hartman & Sasha Levin
+ ====== ================================ ================
-为长期支持选择内核纯粹是维护人员有必要和时间来维护该版本的问题。目前还没有
-为即将发布的任何特定版本提供长期支持的已知计划。
+长期支持内核的选择纯粹是维护人员是否有需求和时间来维护该版本的问题。
+目前还没有为即将发布的任何特定版本提供长期支持的已知计划。
补丁的生命周期
--------------
补丁不会直接从开发人员的键盘进入主线内核。相反，有一个稍微复杂（如果有些非
正式）的过程，旨在确保对每个补丁进行质量审查，并确保每个补丁实现了一个在主线
-中需要的更改。对于小的修复，这个过程可能会很快发生，或者，在大的和有争议的
-变更的情况下，会持续数年。许多开发人员的挫折来自于对这个过程缺乏理解或者
-试图绕过它。
+中需要的更改。对于小的修复，这个过程可能会很快完成，，而对于较大或有争议的
+变更，可能会持续数年。许多开发人员的沮丧来自于对这个过程缺乏理解或者试图绕过它。
-为了减少这种挫折感，本文将描述补丁如何进入内核。下面是一个介绍，它以某种
-理想化的方式描述了这个过程。更详细的过程将在后面的章节中介绍。
+为了减少这种挫败，本文将描述补丁如何进入内核。下面的介绍以一种较为理想化的
+方式描述了这个过程。更详细的过程将在后面的章节中介绍。
-补丁程序经历的阶段通常是：
+补丁通常要经历以下阶段：
-- 设计。这就是补丁的真正需求——以及满足这些需求的方式——的所在。设计工作通常
+- 设计。这就是补丁的真正需求——以及满足这些需求的方式——所在。设计工作通常
是在不涉及社区的情况下完成的，但是如果可能的话，最好是在公开的情况下完成
这项工作；这样可以节省很多稍后再重新设计的时间。
@@ -134,53 +142,51 @@ Greg Kroah-Hartman组成。稳定团队将使用4.x.y编号方案不定期的发
- 更广泛的评审。当补丁接近准备好纳入主线时，它应该被相关的子系统维护人员
接受——尽管这种接受并不能保证补丁会一直延伸到主线。补丁将出现在维护人员的
- 子系统树中，并进入 -next 树（如下所述）。当流程工作时，此步骤将导致对补丁
- 进行更广泛的审查，并发现由于将此补丁与其他人所做的工作集成而导致的任何
+ 子系统树中，并进入 -next 树（如下所述）。当流程进行时，此步骤将会对补丁
+ 进行更广泛的审查，并发现由于将此补丁与其他人所做的工作合并而导致的任何
问题。
-- 请注意，大多数维护人员也有日常工作，因此合并补丁可能不是他们的最高优先级。
- 如果您的补丁程序得到了关于所需更改的反馈，那么您应该进行这些更改，或者为
- 不应该进行这些更改的原因辩护。如果您的补丁没有评审意见，但没有被其相应的
- 子系统或驱动程序维护者接受，那么您应该坚持不懈地将补丁更新到当前内核，使
- 其干净地应用，并不断地将其发送以供审查和合并。
+- 请注意，大多数维护人员也有日常工作，因此合并补丁可能不是他们的最优先工作。
+ 如果您的补丁得到了需要更改的反馈，那么您应该进行这些更改，或者解释为何
+ 不应该进行这些更改。如果您的补丁没有评审意见，也没有被其相应的子系统或
+ 驱动程序维护者接受，那么您应该坚持不懈地将补丁更新到当前内核使其可被正常
+ 应用，并不断地发送它以供审查和合并。
- 合并到主线。最终，一个成功的补丁将被合并到由LinusTorvalds管理的主线存储库
- 中。此时可能会出现更多的评论和/或问题；开发人员应对这些问题并解决出现的
- 任何问题很重要。
+ 中。此时可能会出现更多的评论和/或问题；对开发人员来说应对这些问题并解决
+ 出现的任何问题仍很重要。
-- 稳定版发布。可能受补丁影响的用户数量现在很大，因此可能再次出现新的问题。
+- 稳定版发布。大量用户可能受此补丁影响，因此可能再次出现新的问题。
- 长期维护。虽然开发人员在合并代码后可能会忘记代码，但这种行为往往会给开发
- 社区留下不良印象。合并代码消除了一些维护负担，因为其他代码将修复由API
- 更改引起的问题。但是，如果代码要长期保持有用，原始开发人员应该继续为
- 代码负责。
+ 社区留下不良印象。合并代码消除了一些维护负担，因为其他人将修复由API更改
+ 引起的问题。但是，如果代码要长期保持可用，原始开发人员应该继续为代码负责。
-内核开发人员（或他们的雇主）犯的最大错误之一是试图将流程简化为一个
-“合并到主线”步骤。这种方法总是会让所有相关人员感到沮丧。
+内核开发人员（或他们的雇主）犯的最大错误之一是试图将流程简化为一个“合并到
+主线”步骤。这种方法总是会让所有相关人员感到沮丧。
补丁如何进入内核
----------------
只有一个人可以将补丁合并到主线内核存储库中：LinusTorvalds。但是，在进入
2.6.38内核的9500多个补丁中，只有112个（大约1.3%）是由Linus自己直接选择的。
-内核项目已经发展到一个规模，没有一个开发人员可以在没有支持的情况下检查和
-选择每个补丁。内核开发人员处理这种增长的方式是通过使用围绕信任链构建的
-助理系统。
+内核项目已经发展到一个没有一个开发人员可以在没有支持的情况下检查和选择每个
+补丁的规模。内核开发人员处理这种增长的方式是使用围绕信任链构建的助理系统。
-内核代码库在逻辑上被分解为一组子系统：网络、特定的体系结构支持、内存管理、
-视频设备等。大多数子系统都有一个指定的维护人员，开发人员对该子系统中的代码
-负有全部责任。这些子系统维护者（松散地）是他们所管理的内核部分的守护者；
-他们（通常）会接受一个补丁以包含到主线内核中。
+内核代码库在逻辑上被分解为一组子系统：网络、特定体系结构支持、内存管理、视
+频设备等。大多数子系统都有一个指定的维护人员，其总体负责该子系统中的代码。
+这些子系统维护者（松散地）是他们所管理的内核部分的“守门员”；他们（通常）
+会接受一个补丁以包含到主线内核中。
-子系统维护人员每个人都使用git源代码管理工具管理自己版本的内核源代码树。Git
-等工具（以及Quilt或Mercurial等相关工具）允许维护人员跟踪补丁列表，包括作者
+子系统维护人员每个人都管理着自己版本的内核源代码树，通常（并非总是）使用Git。
+Git等工具（以及Quilt或Mercurial等相关工具）允许维护人员跟踪补丁列表，包括作者
信息和其他元数据。在任何给定的时间，维护人员都可以确定他或她的存储库中的哪
些补丁在主线中找不到。
-当合并窗口打开时，顶级维护人员将要求Linus从其存储库中“拉出”他们为合并选择
+当合并窗口打开时，顶级维护人员将要求Linus从存储库中“拉出”他们为合并选择
的补丁。如果Linus同意，补丁流将流向他的存储库，成为主线内核的一部分。
-Linus对拉操作中接收到的特定补丁的关注程度各不相同。很明显，有时他看起来很
-关注。但是，作为一般规则，Linus相信子系统维护人员不会向上游发送坏补丁。
+Linus对拉取中接收到的特定补丁的关注程度各不相同。很明显，有时他看起来很
+关注。但是一般来说，Linus相信子系统维护人员不会向上游发送坏补丁。
子系统维护人员反过来也可以从其他维护人员那里获取补丁。例如，网络树是由首先
在专用于网络设备驱动程序、无线网络等的树中积累的补丁构建的。此存储链可以
@@ -195,26 +201,26 @@ Next 树
子系统树链引导补丁流到内核，但它也提出了一个有趣的问题：如果有人想查看为
下一个合并窗口准备的所有补丁怎么办？开发人员将感兴趣的是，还有什么其他的
-更改有待解决，以查看是否存在需要担心的冲突；例如，更改核心内核函数原型的
+更改有待解决，以了解是否存在需要担心的冲突；例如，更改核心内核函数原型的
修补程序将与使用该函数旧形式的任何其他修补程序冲突。审查人员和测试人员希望
-在所有这些变更到达主线内核之前，能够访问它们的集成形式中的变更。您可以从所有
-有趣的子系统树中提取更改，但这将是一项大型且容易出错的工作。
+在所有这些变更到达主线内核之前，能够访问它们的集成形式的变更。您可以从所有
+相关的子系统树中提取更改，但这将是一项复杂且容易出错的工作。
-答案以-next树的形式出现，在这里子系统树被收集以供测试和审查。Andrew Morton
-维护的这些旧树被称为“-mm”（用于内存管理，这就是它的启动名字）。-mm 树集成了
-一长串子系统树中的补丁；它还包含一些旨在帮助调试的补丁。
+解决方案以-next树的形式出现，在这里子系统树被收集以供测试和审查。这些树中
+由Andrew Morton维护的较老的一个，被称为“-mm”（用于内存管理，创建时为此）。
+-mm 树集成了一长串子系统树中的补丁；它还包含一些旨在帮助调试的补丁。
除此之外，-mm 还包含大量由Andrew直接选择的补丁。这些补丁可能已经发布在邮件
-列表上，或者它们可能应用于内核中没有指定子系统树的部分。结果，-mm 作为一种
-最后手段的子系统树运行；如果没有其他明显的路径可以让补丁进入主线，那么它很
-可能以-mm 结束。累积在-mm 中的各种补丁最终将被转发到适当的子系统树，或者直接
+列表上，或者它们可能应用于内核中未指定子系统树的部分。同时，-mm 作为最后
+手段的子系统树；如果没有其他明显的路径可以让补丁进入主线，那么它很可能最
+终选择-mm 树。累积在-mm 中的各种补丁最终将被转发到适当的子系统树，或者直接
发送到Linus。在典型的开发周期中，大约5-10%的补丁通过-mm 进入主线。
-当前-mm 补丁可在“mmotm”（-mm of the moment）目录中找到，地址：
+当前-mm 补丁可在“mmotm”（-mm of the moment）目录中找到：
https://www.ozlabs.org/~akpm/mmotm/
-然而，使用mmotm树可能是一种令人沮丧的体验；它甚至可能无法编译。
+然而，使用MMOTM树可能会十分令人头疼；它甚至可能无法编译。
下一个周期补丁合并的主要树是linux-next，由Stephen Rothwell 维护。根据设计
linux-next 是下一个合并窗口关闭后主线的快照。linux-next树在Linux-kernel 和
@@ -228,49 +234,48 @@ Linux-next 已经成为内核开发过程中不可或缺的一部分；在一个
Staging 树
----------
-内核源代码树包含drivers/staging/directory，其中有许多驱动程序或文件系统的
-子目录正在被添加到内核树中。它们然需要更多的工作的时候可以保留在
-driver/staging目录中；一旦完成，就可以将它们移到内核中。这是一种跟踪不符合
-Linux内核编码或质量标准的驱动程序的方法，但人们可能希望使用它们并跟踪开发。
+内核源代码树包含drivers/staging/目录，其中有许多驱动程序或文件系统的子目录
+正在被添加到内核树中。它们在仍然需要更多的修正的时候可以保留在driver/staging/
+目录中；一旦完成，就可以将它们移到内核中。这是一种跟踪不符合Linux内核编码或
+质量标准的驱动程序的方法，人们可能希望使用它们并跟踪开发。
-Greg Kroah Hartman 目前负责维护staging 树。仍需要工作的驱动程序将发送给他，
+Greg Kroah Hartman 目前负责维护staging 树。仍需要修正的驱动程序将发送给他，
每个驱动程序在drivers/staging/中都有自己的子目录。除了驱动程序源文件之外，
-目录中还应该有一个TODO文件。todo文件列出了驱动程序需要接受的挂起的工作，
+目录中还应该有一个TODO文件。TODO文件列出了驱动程序需要接受的暂停的工作，
以及驱动程序的任何补丁都应该抄送的人员列表。当前的规则要求，staging的驱动
程序必须至少正确编译。
-Staging 是一种相对容易的方法，可以让新的驱动程序进入主线，幸运的是，他们会
-引起其他开发人员的注意，并迅速改进。然而，进入staging并不是故事的结尾；
-staging中没有看到常规进展的代码最终将被删除。经销商也倾向于相对不愿意使用
-staging驱动程序。因此，在成为一名合适的主线驱动的路上，staging 充其量只是
-一个停留。
+Staging 是一种让新的驱动程序进入主线的相对容易的方法，它们会幸运地引起其他
+开发人员的注意，并迅速改进。然而，进入staging并不是故事的结尾；staging中
+没有看到常规进展的代码最终将被删除。经销商也倾向于相对不愿意使用staging驱动
+程序。因此，在成为一个合适的主线驱动的路上，staging 仅是一个中转站。
工具
----
从上面的文本可以看出，内核开发过程在很大程度上依赖于在不同方向上聚集补丁的
能力。如果没有适当强大的工具，整个系统将无法在任何地方正常工作。关于如何使用
-这些工具的教程远远超出了本文档的范围，但是还是有一些指南的空间。
+这些工具的教程远远超出了本文档的范围，但还是用一点篇幅介绍一些关键点。
到目前为止，内核社区使用的主要源代码管理系统是git。Git是在自由软件社区中开发
的许多分布式版本控制系统之一。它非常适合内核开发，因为它在处理大型存储库和
-大量补丁时性能非常好。它还有一个难以学习和使用的名声，尽管随着时间的推移它
-变得更好了。对于内核开发人员来说，对Git的某种熟悉几乎是一种要求；即使他们不
-将它用于自己的工作，他们也需要Git来跟上其他开发人员（以及主线）正在做的事情。
+大量补丁时性能非常好。它也以难以学习和使用而著称，尽管随着时间的推移它变得
+更好了。对于内核开发人员来说，对Git的某种熟悉几乎是一种要求；即使他们不将它
+用于自己的工作，他们也需要Git来跟上其他开发人员（以及主线）正在做的事情。
-现在几乎所有的Linux发行版都打包了Git。主页位于：
+现在几乎所有的Linux发行版都打包了Git。Git主页位于：
https://git-scm.com/
-那个页面有指向文档和教程的指针。
+此页面包含了文档和教程的链接。
-在不使用git的内核开发人员中，最流行的选择几乎肯定是mercurial：
+在不使用git的内核开发人员中，最流行的选择几乎肯定是Mercurial：
http://www.seleric.com/mercurial/
Mercurial与Git共享许多特性，但它提供了一个界面，许多人觉得它更易于使用。
-另一个值得了解的工具是quilt:
+另一个值得了解的工具是Quilt:
https://savannah.nongnu.org/projects/quilt
@@ -282,79 +287,79 @@ Quilt 是一个补丁管理系统，而不是源代码管理系统。它不会
邮件列表
--------
-大量的Linux内核开发工作是通过邮件列表完成的。如果不在某个地方加入至少一个列表，
-就很难成为社区中一个功能完备的成员。但是，Linux邮件列表对开发人员来说也是一个
-潜在的危险，他们可能会被一堆电子邮件淹没，违反Linux列表上使用的约定，或者
-两者兼而有之。
+大量的Linux内核开发工作是通过邮件列表完成的。如果不加入至少一个某个列表，
+就很难成为社区中的一个“全功能”成员。但是，Linux邮件列表对开发人员来说也是
+一个潜在的危险，他们可能会被一堆电子邮件淹没、违反Linux列表上使用的约定，
+或者两者兼而有之。
大多数内核邮件列表都在vger.kernel.org上运行；主列表位于：
http://vger.kernel.org/vger-lists.html
-不过，也有一些列表托管在别处；其中一些列表位于lists.redhat.com。
+不过，也有一些列表托管在别处；其中一些列表位于
+redhat.com/mailman/listinfo。
-当然，内核开发的核心邮件列表是linux-kernel。这个名单是一个令人生畏的地方；
-每天的信息量可以达到500条，噪音很高，谈话技术性很强，参与者并不总是表现出
+当然，内核开发的核心邮件列表是linux-kernel。这个列表是一个令人生畏的地方：
+每天的信息量可以达到500条，噪音很高，谈话技术性很强，且参与者并不总是表现出
高度的礼貌。但是，没有其他地方可以让内核开发社区作为一个整体聚集在一起；
-避免使用此列表的开发人员将错过重要信息。
+不使用此列表的开发人员将错过重要信息。
-有一些提示可以帮助在linux-kernel生存：
+以下一些提示可以帮助在linux-kernel生存：
-- 将邮件转移到单独的文件夹，而不是主邮箱。我们必须能够持续地忽略洪流。
+- 将邮件转移到单独的文件夹，而不是主邮箱文件夹。我们必须能够持续地忽略洪流。
-- 不要试图跟踪每一次谈话-其他人都不会。重要的是要对感兴趣的主题（尽管请
- 注意，长时间的对话可以在不更改电子邮件主题行的情况下偏离原始主题）和参与
- 的人进行筛选。
+- 不要试图跟上每一次谈话——没人会这样。重要的是要筛选感兴趣的主题（但请注意
+ 长时间的对话可能会偏离原来的主题，尽管未改变电子邮件的主题）和参与的人。
-- 不要挑事。如果有人试图激起愤怒的反应，忽略他们。
+- 不要回复挑事的人。如果有人试图激起愤怒，请忽略他们。
-- 当响应Linux内核电子邮件（或其他列表上的电子邮件）时，请为所有相关人员保留
- cc:header。如果没有强有力的理由（如明确的请求），则不应删除收件人。一定要
- 确保你要回复的人在cc:list中。这个惯例也使你不必在回复邮件时明确要求被抄送。
+- 当回复Linux内核电子邮件（或其他列表上的电子邮件）时，请为所有相关人员保留
+ Cc: 抄送头。如果没有确实的理由（如明确的请求），则不应删除收件人。一定要
+ 确保你要回复的人在抄送列表中。这个惯例也使你不必在回复邮件时明确要求被抄送。
-- 在提出问题之前，搜索列表档案（和整个网络）。有些开发人员可能会对那些显然
+- 在提出问题之前，搜索列表存档（和整个网络）。有些开发人员可能会对那些显然
没有完成家庭作业的人感到不耐烦。
-- 避免贴顶帖（把你的答案放在你要回复的引文上面的做法）。这会让你的回答更难
+- 避免顶部回复（把你的答案放在你要回复的引文上面的做法）。这会让你的回答更难
理解，印象也很差。
-- 询问正确的邮件列表。linux-kernel 可能是通用的讨论点，但它不是从所有子系统
- 中寻找开发人员的最佳场所。
+- 在正确的邮件列表发问。linux-kernel 可能是通用的讨论场所，但它不是寻找所有
+ 子系统开发人员的最佳场所。
-最后一点——找到正确的邮件列表——是开发人员出错的常见地方。在Linux内核上提出与
-网络相关的问题的人几乎肯定会收到一个礼貌的建议，转而在netdev列表上提出，
-因为这是大多数网络开发人员经常出现的列表。还有其他列表可用于scsi、
-video4linux、ide、filesystem等子系统。查找邮件列表的最佳位置是与内核源代码
-一起打包的MAINTAINERS文件。
+最后一点——找到正确的邮件列表——是开发人员常出错的地方。在linux-kernel上
+提出与网络相关的问题的人几乎肯定会收到一个礼貌的建议，转到netdev列表上提出，
+因为这是大多数网络开发人员经常出现的列表。还有其他列表可用于scsi、video4linux、
+ide、filesystem等子系统。查找邮件列表的最佳位置是与内核源代码一起打包的
+MAINTAINERS文件。
开始内核开发
------------
-关于如何开始内核开发过程的问题很常见——来自个人和公司。同样常见的是错误，这
-使得关系的开始比必须的更困难。
+关于如何开始内核开发过程的问题很常见——个人和公司皆然。同样常见的是失误，这
+使得关系的开始比本应的更困难。
公司通常希望聘请知名的开发人员来启动开发团队。实际上，这是一种有效的技术。
-但它也往往是昂贵的，而且没有增长经验丰富的内核开发人员储备。考虑到时间的
-投入，可以让内部开发人员加快Linux内核的开发速度。花这个时间可以让雇主拥有
-一批了解内核和公司的开发人员，他们也可以帮助培训其他人。从中期来看，这往往
-是更有利可图的方法。
+但它也往往是昂贵的，而且对增加有经验的内核开发人员的数量没有多大帮助。考
+虑到时间投入，可以让内部开发人员加快Linux内核的开发速度。利用这段时间可以
+让雇主拥有一批既了解内核又了解公司的开发人员，还可以帮助培训其他人。从中期
+来看，这通常是更有利可图的方法。
可以理解的是，单个开发人员往往对起步感到茫然。从一个大型项目开始可能会很
-吓人；人们往往想先用一些较小的东西来测试水域。这是一些开发人员开始创建修补
-拼写错误或轻微编码风格问题的补丁的地方。不幸的是，这样的补丁会产生一定程度
-的噪音，这会分散整个开发社区的注意力，因此，越来越多的人看不起它们。希望向
-社区介绍自己的新开发人员将无法通过这些方式获得他们想要的那种接待。
+吓人；人们往往想先用一些较小的东西来试试水。由此，一些开发人员开始创建修补
+拼写错误或轻微编码风格问题的补丁。不幸的是，这样的补丁会产生一定程度的噪音，
+这会分散整个开发社区的注意力，因此，它们越来越被人不看重。希望向社区介绍
+自己的新开发人员将无法通过这些方式获得他们期待的反响。
-Andrew Morton 为有抱负的内核开发人员提供了这个建议
+Andrew Morton 为有抱负的内核开发人员提供了如下建议
::
- 所有内核初学者的No.1项目肯定是“确保内核在所有的机器上，你可以触摸
- 到的，始终运行良好" 通常这样做的方法是与其他人一起解决问题（这
- 可能需要坚持！）但这很好——这是内核开发的一部分
+ 所有内核开发者的第一个项目肯定应该是“确保内核在您可以操作的所有
+ 机器上始终完美运行”。通常的方法是和其他人一起解决问题（这可能需
+ 要坚持！），但就是如此——这是内核开发的一部分。
(http://lwn.net/articles/283982/)
-在没有明显问题需要解决的情况下，建议开发人员查看当前的回归和开放式错误列表.
-解决需要修复的问题没有任何缺点；通过解决这些问题，开发人员将获得处理过程的
-经验，同时与开发社区的其他人建立尊重。
+在没有明显问题需要解决的情况下，通常建议开发人员查看当前的回归和开放缺陷
+列表。从来都不缺少需要解决的问题；通过解决这些问题，开发人员将从该过程获得
+经验，同时与开发社区的其他成员建立相互尊重。
--
2.20.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v3 4/9] docs/zh_CN: Improve zh_CN/process/3.Early-stage.rst
2021-03-05 5:25 [PATCH v3 0/9] docs/zh_CN: Improve language in zh_CN/process/ Wu XiangCheng
` (2 preceding siblings ...)
2021-03-05 5:26 ` [PATCH v3 3/9] docs/zh_CN: Improve zh_CN/process/2.Process.rst Wu XiangCheng
@ 2021-03-05 5:27 ` Wu XiangCheng
2021-03-05 5:27 ` [PATCH v3 5/9] docs/zh_CN: Improve zh_CN/process/4.Coding.rst Wu XiangCheng
` (5 subsequent siblings)
9 siblings, 0 replies; 12+ messages in thread
From: Wu XiangCheng @ 2021-03-05 5:27 UTC (permalink / raw)
To: alex.shi; +Cc: corbet, linux-doc
Improve language and grammar of zh_CN/process/3.Early-stage.rst
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
---
.../zh_CN/process/3.Early-stage.rst | 139 +++++++++---------
1 file changed, 73 insertions(+), 66 deletions(-)
diff --git a/Documentation/translations/zh_CN/process/3.Early-stage.rst b/Documentation/translations/zh_CN/process/3.Early-stage.rst
index b8676aec6005..de53dd12e911 100644
--- a/Documentation/translations/zh_CN/process/3.Early-stage.rst
+++ b/Documentation/translations/zh_CN/process/3.Early-stage.rst
@@ -1,7 +1,14 @@
.. include:: ../disclaimer-zh_CN.rst
:Original: :ref:`Documentation/process/3.Early-stage.rst <development_early_stage>`
-:Translator: Alex Shi <alex.shi@linux.alibaba.com>
+
+:Translator:
+
+ 时奎亮 Alex Shi <alex.shi@linux.alibaba.com>
+
+:校译:
+
+ 吴想成 Wu XiangCheng <bobwxc@email.cn>
.. _cn_development_early_stage:
@@ -9,45 +16,45 @@
========
当考虑一个Linux内核开发项目时，很可能会直接跳进去开始编码。然而，与任何重要
-的项目一样，成功的许多基础最好是在第一行代码编写之前就做好了。在早期计划和
-沟通中花费一些时间可以节省更多的时间。
+的项目一样，许多成功的基础最好是在第一行代码编写之前就打下。在早期计划和
+沟通中花费一些时间可以在之后节省更多的时间。
-详述问题
+搞清问题
--------
-与任何工程项目一样，成功的内核增强从要解决的问题的清晰描述开始。在某些情况
-下，这个步骤很容易：例如，当某个特定硬件需要驱动程序时。不过，在其他方面，
-将实际问题与建议的解决方案混淆是很有诱惑力的，这可能会导致困难。
+与任何工程项目一样，成功的内核改善从清晰描述要解决的问题开始。在某些情况
+下，这个步骤很容易：例如当某个特定硬件需要驱动程序时。不过，在其他情况下，
+很容易将实际问题与建议的解决方案混在一起，这可能会导致麻烦。
-举个例子：几年前，使用Linux音频的开发人员寻求一种方法来运行应用程序，而不因
-系统延迟过大而导致退出或其他工件。他们得到的解决方案是一个内核模块，旨在连
-接到Linux安全模块（LSM）框架中；这个模块可以配置为允许特定的应用程序访问
-实时调度程序。这个模块被实现并发送到Linux内核邮件列表，在那里它立即遇到问题。
+举个例子：几年前，Linux音频的开发人员寻求一种方法来运行应用程序，而不会因
+系统延迟过大而导致退出或其他问题。他们得到的解决方案是一个连接到Linux安全
+模块（LSM）框架中的内核模块；这个模块可以配置为允许特定的应用程序访问实时
+调度程序。这个模块被实现并发到linux-kernel邮件列表，在那里它立即遇到了麻烦。
对于音频开发人员来说，这个安全模块足以解决他们当前的问题。但是，对于更广泛的
内核社区来说，这被视为对LSM框架的滥用（LSM框架并不打算授予他们原本不具备的
进程特权），并对系统稳定性造成风险。他们首选的解决方案包括短期的通过rlimit
机制进行实时调度访问，以及长期的减少延迟的工作。
-然而，音频社区看不到他们实施的特定解决方案的过去；他们不愿意接受替代方案。
+然而，音频社区无法超越他们实施的特定解决方案来看问题；他们不愿意接受替代方案。
由此产生的分歧使这些开发人员对整个内核开发过程感到失望；其中一个开发人员返回
-到音频列表并发布了以下内容：
+到audio列表并发布了以下内容：
- 有很多非常好的Linux内核开发人员，但他们往往会被一群傲慢的傻瓜所压倒。
- 试图向这些人传达用户需求是浪费时间。他们太“聪明”了，根本听不到少数人
- 的话。
+ 有很多非常好的Linux内核开发人员，但他们往往会被一群傲慢的傻瓜所压倒。
+ 试图向这些人传达用户需求是浪费时间。他们太“聪明”了，根本听不到少数
+ 人的话。
（http://lwn.net/articles/131776/）
-实际情况不同；与特定模块相比，内核开发人员更关心系统稳定性、长期维护以及找到
-正确的问题解决方案。这个故事的寓意是把重点放在问题上——而不是具体的解决方案
-上——并在投入创建代码之前与开发社区讨论这个问题。
+实际情况却是不同的；与特定模块相比，内核开发人员更关心系统稳定性、长期维护
+以及找到问题的正确解决方案。这个故事的寓意是把重点放在问题上——而不是具体的
+解决方案上——并在开始编写代码之前与开发社区讨论这个问题。
因此，在考虑一个内核开发项目时，我们应该得到一组简短问题的答案：
- - 究竟需要解决的问题是什么？
+ - 需要解决的问题究竟是什么？
- - 受此问题影响的用户是谁？解决方案应该解决哪些用例？
+ - 受此问题影响的用户有哪些？解决方案应该解决哪些使用案例？
- 内核现在为何没能解决这个问题？
@@ -62,100 +69,100 @@
- 很可能问题是由内核以您不理解的方式解决的。Linux内核很大，具有许多不明显
的特性和功能。并不是所有的内核功能都像人们所希望的那样有文档记录，而且很
- 容易遗漏一些东西。你的作者发出了一个完整的驱动程序，复制了一个新作者不
- 知道的现有驱动程序。重新设计现有轮子的代码不仅浪费，而且不会被接受到主线
+ 容易遗漏一些东西。某作者发布了一个完整的驱动程序，重复了一个其不
+ 知道的现有驱动程序。重新发明现有轮子的代码不仅浪费，而且不会被接受到主线
内核中。
- - 建议的解决方案中可能有一些元素不适用于主线合并。在编写代码之前，最好先
- 了解这样的问题。
+ - 建议的解决方案中可能有一些要素不适合并入主线。在编写代码之前，最好先了解
+ 这样的问题。
- 其他开发人员完全有可能考虑过这个问题；他们可能有更好的解决方案的想法，并且
可能愿意帮助创建这个解决方案。
在内核开发社区的多年经验给了我们一个明确的教训：闭门设计和开发的内核代码总是
有一些问题，这些问题只有在代码发布到社区中时才会被发现。有时这些问题很严重，
-需要数月或数年的努力才能使代码达到内核社区的标准。一些例子包括：
+需要数月或数年的努力才能使代码达到内核社区的标准。例如：
- 设计并实现了单处理器系统的DeviceScape网络栈。只有使其适合于多处理器系统，
- 才能将其合并到主线中。在代码中改装锁等等是一项困难的任务；因此，这段代码
+ 才能将其合并到主线中。在代码中修改锁等等是一项困难的任务；因此，这段代码
（现在称为mac80211）的合并被推迟了一年多。
- Reiser4文件系统包含许多功能，核心内核开发人员认为这些功能应该在虚拟文件
系统层中实现。它还包括一些特性，这些特性在不将系统暴露于用户引起的死锁的
- 情况下是不容易实现的。这些问题的最新发现——以及对其中一些问题的拒绝——已经
- 导致Reiser4远离了主线内核。
+ 情况下是不容易实现的。这些问题过迟发现——以及拒绝处理其中一些问题——已经
+ 导致Reiser4置身主线内核之外。
- Apparmor安全模块以被认为不安全和不可靠的方式使用内部虚拟文件系统数据结构。
- 这种担心（包括其他）使Apparmor多年不在主线上。
+ 这种担心（包括其他）使Apparmor多年来无法进入主线。
-在每一种情况下，通过与内核开发人员的早期讨论，可以避免大量的痛苦和额外的工作。
+在这些情况下，与内核开发人员的早期讨论，可以避免大量的痛苦和额外的工作。
-找谁交流
---------
+找谁交流？
+----------
当开发人员决定公开他们的计划时，下一个问题是：我们从哪里开始？答案是找到正确
的邮件列表和正确的维护者。对于邮件列表，最好的方法是在维护者(MAINTAINERS)文件
-中查找要发布的相关位置。如果有一个合适的子系统列表，那么发布它通常比在Linux
-内核上发布更可取；您更有可能接触到在相关子系统中具有专业知识的开发人员，并且
-环境可能具支持性。
+中查找要发布的相关位置。如果有一个合适的子系统列表，那么其上发布通常比在
+linux-kernel上发布更可取；您更有可能接触到在相关子系统中具有专业知识的开发
+人员，并且环境可能具支持性。
-找到维护人员可能会有点困难。同样，维护者文件是开始的地方。但是，该文件往往不总
-是最新的，并且并非所有子系统都在那里表示。实际上，维护者文件中列出的人员可能
+找到维护人员可能会有点困难。同样，维护者文件是开始的地方。但是，该文件往往不
+是最新的，并且并非所有子系统都在那里显示。实际上，维护者文件中列出的人员可能
不是当前实际担任该角色的人员。因此，当对联系谁有疑问时，一个有用的技巧是使用
-git（尤其是“git-log”）查看感兴趣的子系统中当前活动的用户。看看谁在写补丁，
-如果有人的话，谁会在这些补丁上加上用线签名的。这些人将是帮助新开发项目的最佳
-人选。
+git（尤其是“git-log”）查看感兴趣的子系统中当前活动的用户。看看谁在写补丁、
+谁会在这些补丁上加上Signed-off-by行签名（如有）。这些人将是帮助新开发项目的
+最佳人选。
-找到合适的维护者的任务有时是非常具有挑战性的，以至于内核开发人员添加了一个
-脚本来简化过程：
+找到合适的维护者有时是非常具有挑战性的，以至于内核开发人员添加了一个脚本来
+简化这个过程：
::
.../scripts/get_maintainer.pl
-当给定“-f”选项时，此脚本将返回给定文件或目录的当前维护者。如果在命令行上传递
-了一个补丁，它将列出可能接收补丁副本的维护人员。有许多选项可以调节
-get_maintainer.pl搜索维护者的难易程度；请小心使用更具攻击性的选项，因为最终
+当给定“-f”选项时，此脚本将返回指定文件或目录的当前维护者。如果在命令行上
+给出了一个补丁，它将列出可能接收补丁副本的维护人员。有许多选项可以调节
+get_maintainer.pl搜索维护者的严格程度；请小心使用更激进的选项，因为最终结果
可能会包括对您正在修改的代码没有真正兴趣的开发人员。
-如果所有其他方法都失败了，那么与Andrew Morton交谈可以成为一种有效的方法来跟踪
-特定代码段的维护人员。
+如果所有其他方法都失败了，那么与Andrew Morton交流是跟踪特定代码段维护人员
+的一种有效方法。
何时邮寄？
----------
-如果可能的话，在早期阶段发布你的计划只会有帮助。描述正在解决的问题以及已经
+如果可能的话，在早期阶段发布你的计划只会更有帮助。描述正在解决的问题以及已经
制定的关于如何实施的任何计划。您可以提供的任何信息都可以帮助开发社区为项目
提供有用的输入。
-在这个阶段可能发生的一件令人沮丧的事情不是敌对的反应，而是很少或根本没有
-反应。可悲的事实是：（1）内核开发人员往往很忙；（2）不缺少有宏伟计划和很少
-代码（甚至代码前景）支持他们的人；（3）没有人有义务审查或评论别人发表的
-想法。除此之外，高级设计常常隐藏一些问题，这些问题只有在有人真正尝试实现
-这些设计时才会被发现；因此，内核开发人员宁愿看到代码。
+在这个阶段可能发生的一件令人沮丧的事情不是得到反对意见，而是很少或根本没有
+反馈。令人伤心的事实是：（1）内核开发人员往往很忙；（2）不缺少有宏伟计划但
+代码（甚至代码设想）很少的人去支持他们；（3）没有人有义务审查或评论别人发表
+的想法。除此之外，高层级的设计常常隐藏着一些问题，这些问题只有在有人真正尝试
+实现这些设计时才会被发现；因此，内核开发人员宁愿看到代码。
-如果发表评论的请求在评论的方式上没有什么效果，不要假设这意味着对项目没有
-兴趣。不幸的是，你也不能假设你的想法没有问题。在这种情况下，最好的做法是
-继续进行，把你的进展随时通知社区。
+如果发布请求评论（RFC）并没得到什么有用的评论，不要以为这意味着无人对此项目
+有兴趣，同时你也不能假设你的想法没有问题。在这种情况下，最好的做法是继续进
+行，把你的进展随时通知社区。
获得官方认可
-----------------------
-如果您的工作是在公司环境中完成的，就像大多数Linux内核工作一样，显然，在您将
-公司的计划或代码发布到公共邮件列表之前，必须获得适当授权的经理的许可。发布
-不确定是否兼容GPL的代码可能是有特别问题的；公司的管理层和法律人员越早能够就
-发布内核开发项目达成一致，对参与的每个人都越好。
+如果您的工作是在公司环境中完成的，就像大多数Linux内核工作一样；显然，在您将
+公司的计划或代码发布到公共邮件列表之前，必须获得有适当权利经理的许可。发布
+不确定是否兼容GPL的代码尤其会带来问题；公司的管理层和法律人员越早能够就发布
+内核开发项目达成一致，对参与的每个人都越好。
一些读者可能会认为他们的核心工作是为了支持还没有正式承认存在的产品。将雇主
的计划公布在公共邮件列表上可能不是一个可行的选择。在这种情况下，有必要考虑
保密是否真的是必要的；通常不需要把开发计划关在门内。
-也就是说，有些情况下，一家公司在开发过程的早期就不能合法地披露其计划。拥有
-经验丰富的内核开发人员的公司可以选择以开环的方式进行，前提是他们以后能够避免
+的确，有些情况下一家公司在开发过程的早期无法合法地披露其计划。拥有经验丰富
+的内核开发人员的公司可能选择以开环的方式进行开发，前提是他们以后能够避免
严重的集成问题。对于没有这种内部专业知识的公司，最好的选择往往是聘请外部
-开发商根据保密协议审查计划。Linux基金会运行了一个NDA程序，旨在帮助解决这种
-情况；
+开发者根据保密协议审查计划。Linux基金会运行了一个NDA程序，旨在帮助解决这种
+情况；更多信息参见：
- http://www.linuxfoundation.org/en/NDA_program
+ http://www.linuxfoundation.org/nda/
这种审查通常足以避免以后出现严重问题，而无需公开披露项目。
--
2.20.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v3 5/9] docs/zh_CN: Improve zh_CN/process/4.Coding.rst
2021-03-05 5:25 [PATCH v3 0/9] docs/zh_CN: Improve language in zh_CN/process/ Wu XiangCheng
` (3 preceding siblings ...)
2021-03-05 5:27 ` [PATCH v3 4/9] docs/zh_CN: Improve zh_CN/process/3.Early-stage.rst Wu XiangCheng
@ 2021-03-05 5:27 ` Wu XiangCheng
2021-03-05 5:27 ` [PATCH v3 6/9] docs/zh_CN: Improve zh_CN/process/5.Posting.rst Wu XiangCheng
` (4 subsequent siblings)
9 siblings, 0 replies; 12+ messages in thread
From: Wu XiangCheng @ 2021-03-05 5:27 UTC (permalink / raw)
To: alex.shi; +Cc: corbet, linux-doc
Improve language and grammar of zh_CN/process/4.Coding.rst
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
---
.../translations/zh_CN/process/4.Coding.rst | 279 +++++++++---------
1 file changed, 141 insertions(+), 138 deletions(-)
diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst
index 66cd8ee07606..94f7f866f103 100644
--- a/Documentation/translations/zh_CN/process/4.Coding.rst
+++ b/Documentation/translations/zh_CN/process/4.Coding.rst
@@ -1,155 +1,160 @@
.. include:: ../disclaimer-zh_CN.rst
:Original: :ref:`Documentation/process/4.Coding.rst <development_coding>`
-:Translator: Alex Shi <alex.shi@linux.alibaba.com>
+
+:Translator:
+
+ 时奎亮 Alex Shi <alex.shi@linux.alibaba.com>
+
+:校译:
+
+ 吴想成 Wu XiangCheng <bobwxc@email.cn>
.. _cn_development_coding:
使代码正确
======================
-虽然对于一个坚实的、面向社区的设计过程有很多话要说，但是任何内核开发项目的
-证明都在生成的代码中。它是将由其他开发人员检查并合并（或不合并）到主线树中
+虽然一个坚实的、面向社区的设计过程有很多值得说道的，但是任何内核开发项目工作
+的证明都反映在代码中。它是将由其他开发人员检查并合并（或不合并）到主线树中
的代码。所以这段代码的质量决定了项目的最终成功。
-本节将检查编码过程。我们将从内核开发人员出错的几种方式开始。然后重点将转移
-到正确的事情和可以帮助这个任务的工具上。
+本节将检查编码过程。我们将从内核开发人员常犯的几种错误开始。然后重点将转移
+到正确的做法和相关有用的工具上。
陷阱
----
-编码风格
+代码风格
********
-内核长期以来都有一种标准的编码风格，如
+内核长期以来都有其标准的代码风格，如
:ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>`
-中所述。在大部分时间里，该文件中描述的政策被认为至多是建议性的。因此，内核
-中存在大量不符合编码风格准则的代码。代码的存在会给内核开发人员带来两个独立
-的危害。
-
-首先，要相信内核编码标准并不重要，也不强制执行。事实上，如果没有按照标准对代
-码进行编码，那么向内核添加新代码是非常困难的；许多开发人员甚至会在审查代码之
-前要求对代码进行重新格式化。一个与内核一样大的代码库需要一些统一的代码，以使
-开发人员能够快速理解其中的任何部分。所以已经没有空间来存放奇怪的格式化代码了。
-
-偶尔，内核的编码风格会与雇主的强制风格发生冲突。在这种情况下，内核的风格必须
-在代码合并之前获胜。将代码放入内核意味着以多种方式放弃一定程度的控制权——包括
-控制代码的格式化方式。
-
-另一个陷阱是假定已经在内核中的代码迫切需要编码样式的修复。开发人员可能会开始
-生成重新格式化补丁，作为熟悉过程的一种方式，或者作为将其名称写入内核变更日志
-的一种方式，或者两者兼而有之。但是纯编码风格的修复被开发社区视为噪音；它们往
-往受到冷遇。因此，最好避免使用这种类型的补丁。由于其他原因，在处理一段代码的
-同时修复它的样式是很自然的，但是编码样式的更改不应该仅为了更改而进行。
-
-编码风格的文档也不应该被视为绝对的法律，这是永远不会被违反的。如果有一个很好
-的理由反对这种样式（例如，如果拆分为适合80列限制的行，那么它的可读性就会大大
-降低），那么就这样做。
-
-请注意，您还可以使用 ``clang-format`` 工具来帮助您处理这些规则，自动重新格式
-化部分代码，并查看完整的文件，以发现编码样式错误、拼写错误和可能的改进。它还
-可以方便地进行排序，包括对齐变量/宏、回流文本和其他类似任务。有关详细信息，请
-参阅文件 :ref:`Documentation/process/clang-format.rst <clangformat>`
+中所述。在多数时候，该文档中描述的准则至多被认为是建议性的。因此，内核中存在
+大量不符合代码风格准则的代码。这种代码的存在会给内核开发人员带来两方面的危害。
+
+首先，相信内核代码标准并不重要，也不强制执行。但事实上，如果没有按照标准
+编写代码，那么新代码将很难加入到内核中；许多开发人员甚至会在审查代码之前要求
+对代码进行重新格式化。一个像内核这么大的代码库需要一些统一格式的代码，以使
+开发人员能够快速理解其中的任何部分。所以再也经不起奇怪格式的代码的折腾了。
+
+内核的代码风格偶尔会与雇主的强制风格发生冲突。在这种情况下，必须在代码合并
+之前遵从内核代码风格。将代码放入内核意味着以多种方式放弃一定程度的控制权——
+包括控制代码样式。
+
+另一个危害是认为已经在内核中的代码迫切需要修复代码样式。开发者可能会开始编写
+重新格式化补丁，作为熟悉开发过程的一种方式，或者作为将其名字写入内核变更日志
+的一种方式，或者两者兼而有之。但是纯代码风格的修复被开发社区视为噪音，它们往
+往受到冷遇。因此，最好避免编写这种类型的补丁。在由于其他原因处理一段代码的
+同时顺带修复其样式是很自然的，但是不应该仅为了更改代码样式而更改之。
+
+代码风格文档也不应该被视为绝对不可违反的规则。如果有一个足够的理由反对这种
+样式（例如为了80列限制拆分行会导致可读性大大降低），那么就这样做吧。
+
+注意您还可以使用 ``clang-format`` 工具来帮助您处理这些规则，快速自动重新格式
+化部分代码，和审阅完整的文件以发现代码样式错误、拼写错误和可能的改进。它还
+可以方便地排序 ``#includes`` 、对齐变量/宏、重排文本和其他类似任务。有关详细
+信息，请参阅文档 :ref:`Documentation/process/clang-format.rst <clangformat>`
抽象层
******
计算机科学教授教学生以灵活性和信息隐藏的名义广泛使用抽象层。当然，内核广泛
-地使用了抽象；任何涉及数百万行代码的项目都不能做到这一点并存活下来。但经验
-表明，过度或过早的抽象可能和过早的优化一样有害。抽象应用于所需的级别，
+地使用了抽象；任何涉及数百万行代码的项目都必须做到这一点以存续下来。但经验
+表明，过度或过早的抽象可能和过早的优化一样有害。抽象应用在适当层级，
不要过度。
-在一个简单的级别上，考虑一个函数的参数，该参数总是由所有调用方作为零传递。
-我们可以保留这个论点: 以防有人最终需要使用它提供的额外灵活性。不过，到那时，
-实现这个额外参数的代码很有可能以某种从未被注意到的微妙方式被破坏——因为它从
-未被使用过。或者，当需要额外的灵活性时，它不会以符合程序员早期期望的方式来
-这样做。内核开发人员通常会提交补丁来删除未使用的参数；一般来说，首先不应该
-添加这些参数。
+简单点，先考虑一个调用时始终只有一个参数且总为零的函数。我们可以保留这个参数，
+以在需要使用它时提供的额外灵活性。不过，在那时实现了这个额外参数的代码很有
+可能以某种从未被注意到的微妙方式被破坏——因为它从未被使用过。或者当需要额外
+的灵活性时，它并未以符合程序员当初期望的方式来实现。内核开发人员通常会提交
+补丁来删除未使用的参数；一般来说，一开始就不应该添加这些参数。
-隐藏硬件访问的抽象层——通常允许大量的驱动程序在多个操作系统中使用——尤其不受
+隐藏硬件访问的抽象层——通常为了允许大量的驱动程序兼容多个操作系统——尤其不受
欢迎。这样的层使代码变得模糊，可能会造成性能损失；它们不属于Linux内核。
-另一方面，如果您发现自己从另一个内核子系统复制了大量的代码，那么现在是时候
-问一下，事实上，将这些代码中的一些提取到单独的库中，或者在更高的层次上实现
-这些功能是否有意义。在整个内核中复制相同的代码没有价值。
+另一方面，如果您发现自己从另一个内核子系统复制了大量的代码，那么是时候
+了解一下：是否需要将这些代码中的部分提取到单独的库中，或者在更高的层次上
+实现这些功能。在整个内核中复制相同的代码没有价值。
#ifdef 和预处理
***************
-C预处理器似乎给一些C程序员带来了强大的诱惑，他们认为它是一种有效地将大量灵
-活性编码到源文件中的方法。但是预处理器不是C，大量使用它会导致代码对其他人来
-说更难读取，对编译器来说更难检查正确性。大量的预处理器几乎总是代码需要一些
+C预处理器似乎给一些C程序员带来了强大的诱惑，他们认为它是一种将大量灵活性加入
+源代码中的方法。但是预处理器不是C，大量使用它会导致代码对其他人来说更难阅读，
+对编译器来说更难检查正确性。使用了大量预处理器几乎总是代码需要一些
清理工作的标志。
-使用ifdef的条件编译实际上是一个强大的功能，它在内核中使用。但是很少有人希望
-看到代码被大量地撒上ifdef块。作为一般规则，ifdef的使用应尽可能限制在头文件
-中。有条件编译的代码可以限制函数，如果代码不存在，这些函数就会变成空的。然后
-编译器将悄悄地优化对空函数的调用。结果是代码更加清晰，更容易理解。
+使用#ifdef的条件编译实际上是一个强大的功能，它在内核中使用。但是很少有人希望
+看到代码被铺满#ifdef块。一般规定，ifdef的使用应尽可能限制在头文件中。条件
+编译代码可以限制函数，如果代码不存在，这些函数就直接变成空的。然后编译器将
+悄悄地优化对空函数的调用。使得代码更加清晰，更容易理解。
-C预处理器宏存在许多危险，包括可能对具有副作用且没有类型安全性的表达式进行多
-重评估。如果您试图定义宏，请考虑创建一个内联函数。结果相同的代码，但是内联
-函数更容易读取，不会多次计算其参数，并且允许编译器对参数和返回值执行类型检查。
+C预处理器宏存在许多危险性，包括可能对具有副作用且没有类型安全的表达式进行多
+重评估。如果您试图定义宏，请考虑创建一个内联函数替代。结果相同的代码，内联
+函数更容易阅读，不会多次计算其参数，并且允许编译器对参数和返回值执行类型检查。
内联函数
********
不过，内联函数本身也存在风险。程序员可以倾心于避免函数调用和用内联函数填充源
文件所固有的效率。然而，这些功能实际上会降低性能。因为它们的代码在每个调用站
-点都被复制，所以它们最终会增加编译内核的大小。反过来，这会对处理器的内存缓存
-造成压力，从而大大降低执行速度。通常，内联函数应该非常小，而且相对较少。毕竟，
-函数调用的成本并不高；大量内联函数的创建是过早优化的典型例子。
+点都被复制一遍，所以最终会增加编译内核的大小。此外，这也对处理器的内存缓存
+造成压力，从而大大降低执行速度。通常内联函数应该非常小，而且相对较少。毕竟
+函数调用的成本并不高；大量创建内联函数是过早优化的典型例子。
-一般来说，内核程序员会忽略缓存效果，这会带来危险。在开始的数据结构课程中，经
-典的时间/空间权衡通常不适用于当代硬件。空间就是时间，因为一个大的程序比一个
+一般来说，内核程序员会自冒风险忽略缓存效果。在数据结构课程开头中的经典
+时间/空间权衡通常不适用于当代硬件。空间 *就是* 时间，因为一个大的程序比一个
更紧凑的程序运行得慢。
-最近的编译器在决定一个给定函数是否应该被内联方面扮演着越来越积极的角色。
-因此，“inline”关键字的自由放置可能不仅仅是过度的，它也可能是无关的。
+较新的编译器越来越激进地决定一个给定函数是否应该内联。因此，随意放置使用
+“inline”关键字可能不仅仅是过度的，也可能是无用的。
锁
**
-2006年5月，“deviceescape”网络堆栈在GPL下发布，并被纳入主线内核。这是一个受
-欢迎的消息；对Linux中无线网络的支持充其量被认为是不合格的，而deviceescape
-堆栈提供了修复这种情况的承诺。然而，直到2007年6月（2.6.22），这段代码才真
+2006年5月，“deviceescape”网络堆栈在前呼后拥下以GPL发布，并被纳入主线内核。
+这是一个受欢迎的消息；Linux中对无线网络的支持充其量被认为是不合格的，而
+Deviceescape堆栈承诺修复这种情况。然而直到2007年6月（2.6.22），这段代码才真
正进入主线。发生了什么？
-这段代码显示了许多闭门造车的迹象。但一个特别大的问题是，它并不是设计用于多
-处理器系统。在合并这个网络堆栈（现在称为mac80211）之前，需要对其进行一个锁
-方案的改造。
+这段代码出现了许多闭门造车的迹象。但一个大麻烦是，它并不是为多处理器系统而
+设计。在合并这个网络堆栈（现在称为mac80211）之前，需要对其进行一个锁方案的
+改造。
曾经，Linux内核代码可以在不考虑多处理器系统所带来的并发性问题的情况下进行
-开发。然而，现在，这个文件是写在双核笔记本电脑上的。即使在单处理器系统上，
+开发。然而现在，这个文档就是在双核笔记本电脑上写的。即使在单处理器系统上，
为提高响应能力所做的工作也会提高内核内的并发性水平。编写内核代码而不考虑锁
-的日子已经过去很长了。
+的日子早已远去。
可以由多个线程并发访问的任何资源（数据结构、硬件寄存器等）必须由锁保护。新
-的代码应该记住这一要求；事后改装锁是一项相当困难的任务。内核开发人员应该花
-时间充分了解可用的锁原语，以便为作业选择正确的工具。显示对并发性缺乏关注的
-代码进入主线将很困难。
+的代码应该谨记这一要求；事后修改锁是一项相当困难的任务。内核开发人员应该花
+时间充分了解可用的锁原语，以便为工作选择正确的工具。对并发性缺乏关注的代码
+很难进入主线。
回归
****
-最后一个值得一提的危险是：它可能会引起改变（这可能会带来很大的改进），从而
-导致现有用户的某些东西中断。这种变化被称为“回归”，回归已经成为主线内核最不
-受欢迎的。除少数例外情况外，如果回归不能及时修正，会导致回归的变化将被取消。
-最好首先避免回归。
+最后一个值得一提的危险是回归：它可能会引起导致现有用户的某些东西中断的改变
+（这也可能会带来很大的改进）。这种变化被称为“回归”，回归已经成为主线内核
+最不受欢迎的问题。除了少数例外情况，如果回归不能及时修正，会导致回归的修改
+将被取消。最好首先避免回归发生。
-人们常常争论，如果回归让更多人可以工作，远超过产生问题，那么回归是合理的。
-如果它破坏的一个系统却为十个系统带来新的功能，为什么不进行更改呢？2007年7月，
+人们常常争论，如果回归带来的功能远超过产生的问题，那么回归是否为可接受的。
+如果它破坏了一个系统却为十个系统带来新的功能，为何不改改态度呢？2007年7月，
Linus对这个问题给出了最佳答案:
::
- 所以我们不会通过引入新问题来修复错误。那样的谎言很疯狂，没有人知道
- 你是否真的有进展。是前进两步，后退一步，还是向前一步，向后两步？
+
+ 所以我们不会通过引入新问题来修复错误。这种方式是靠不住的，没人知道
+ 是否真的有进展。是前进两步、后退一步，还是前进一步、后退两步？
（http://lwn.net/articles/243460/）
-一种特别不受欢迎的回归类型是用户空间ABI的任何变化。一旦接口被导出到用户空间，
+特别不受欢迎的一种回归类型是用户空间ABI的任何变化。一旦接口被导出到用户空间，
就必须无限期地支持它。这一事实使得用户空间接口的创建特别具有挑战性：因为它们
-不能以不兼容的方式进行更改，所以必须第一次正确地进行更改。因此，用户空间界面
-总是需要大量的思考、清晰的文档和广泛的审查。
+不能以不兼容的方式进行更改，所以必须一次就对。因此，用户空间接口总是需要大量
+的思考、清晰的文档和广泛的审查。
代码检查工具
@@ -157,13 +162,13 @@ Linus对这个问题给出了最佳答案:
至少目前，编写无错误代码仍然是我们中很少人能达到的理想状态。不过，我们希望做
的是，在代码进入主线内核之前，尽可能多地捕获并修复这些错误。为此，内核开发人
-员已经组装了一系列令人印象深刻的工具，可以自动捕获各种各样的模糊问题。计算机
+员已经提供了一系列令人印象深刻的工具，可以自动捕获各种各样的隐藏问题。计算机
发现的任何问题都是一个以后不会困扰用户的问题，因此，只要有可能，就应该使用
自动化工具。
-第一步只是注意编译器产生的警告。当代版本的GCC可以检测（并警告）大量潜在错误。
-通常，这些警告都指向真正的问题。提交以供审阅的代码通常不会产生任何编译器警告。
-在消除警告时，注意了解真正的原因，并尽量避免“修复”，使警告消失而不解决其原因。
+第一步是注意编译器产生的警告。当前版本的GCC可以检测（并警告）大量潜在错误。
+通常，这些警告都指向真正的问题。提交以供审阅的代码一般不会产生任何编译器警告。
+在消除警告时，注意了解真正的原因，并尽量避免仅“修复”使警告消失而不解决其原因。
请注意，并非所有编译器警告都默认启用。使用“make KCFLAGS=-W”构建内核以
获得完整集合。
@@ -172,45 +177,43 @@ Linus对这个问题给出了最佳答案:
子菜单中。对于任何用于开发或测试目的的内核，都应该启用其中几个选项。特别是，
您应该打开：
- - 启用 ENABLE_MUST_CHECK and FRAME_WARN 以获得一组额外的警告，以解决使用不
- 推荐使用的接口或忽略函数的重要返回值等问题。这些警告生成的输出可能是冗长
- 的，但您不必担心来自内核其他部分的警告。
+ - FRAME_WARN 获取大于给定数量的堆栈帧的警告。
+ 这些警告生成的输出可能比较冗长，但您不必担心来自内核其他部分的警告。
- - DEBUG_OBJECTS 将添加代码，以跟踪内核创建的各种对象的生存期，并在出现问题时
- 发出警告。如果要添加创建（和导出）自己的复杂对象的子系统，请考虑添加对对象
- 调试基础结构的支持。
+ - DEBUG_OBJECTS 将添加代码以跟踪内核创建的各种对象的生命周期，并在出现问题
+ 时发出警告。如果你要添加创建（和导出）关于其自己的复杂对象的子系统，请
+ 考虑打开对象调试基础结构的支持。
- DEBUG_SLAB 可以发现各种内存分配和使用错误；它应该用于大多数开发内核。
- - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP and DEBUG_MUTEXES 会发现许多常见的
- 锁定错误.
+ - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP 和 DEBUG_MUTEXES 会发现许多常见的
+ 锁错误。
-还有很多其他调试选项，其中一些将在下面讨论。其中一些具有显著的性能影响，不应
-一直使用。但是，在学习可用选项上花费的一些时间可能会在短期内得到多次回报。
+还有很多其他调试选项，其中一些将在下面讨论。其中一些有显著的性能影响，不应
+一直使用。在学习可用选项上花费一些时间，可能会在短期内得到许多回报。
-其中一个较重的调试工具是锁定检查器或“lockdep”。该工具将跟踪系统中每个锁
+其中一个较重的调试工具是锁检查器或“lockdep”。该工具将跟踪系统中每个锁
（spinlock或mutex）的获取和释放、获取锁的相对顺序、当前中断环境等等。然后，
-它可以确保总是以相同的顺序获取锁，相同的中断假设适用于所有情况，等等。换句话
-说，lockdep可以找到许多场景，在这些场景中，系统很少会死锁。在部署的系统中，
-这种问题可能会很痛苦（对于开发人员和用户而言）；LockDep允许提前以自动方式
-发现问题。具有任何类型的非普通锁定的代码在提交包含前应在启用lockdep的情况
-下运行。
+它可以确保总是以相同的顺序获取锁，相同的中断假设适用于所有情况等等。换句话
+说，lockdep可以找到许多导致系统死锁的场景。在部署的系统中，这种问题可能会
+很痛苦（对于开发人员和用户而言）；LockDep允许提前以自动方式发现问题。具有
+任何类型的非普通锁的代码在提交合并前应在启用lockdep的情况下运行测试。
作为一个勤奋的内核程序员，毫无疑问，您将检查任何可能失败的操作（如内存分配）
-的返回状态。然而，事实上，最终的故障恢复路径可能完全没有经过测试。未测试的
-代码往往会被破坏；如果所有这些错误处理路径都被执行了几次，那么您可能对代码
+的返回状态。然而，事实上，最终的故障复现路径可能完全没有经过测试。未测试的
+代码往往会出问题；如果所有这些错误处理路径都被执行了几次，那么您可能对代码
更有信心。
内核提供了一个可以做到这一点的错误注入框架，特别是在涉及内存分配的情况下。
-启用故障注入后，内存分配的可配置百分比将失败；这些失败可以限制在特定的代码
+启用故障注入后，内存分配的可配置失败的百分比；这些失败可以限定在特定的代码
范围内。在启用了故障注入的情况下运行，程序员可以看到当情况恶化时代码如何响
应。有关如何使用此工具的详细信息，请参阅
Documentation/fault-injection/fault-injection.rst。
-使用“sparse”静态分析工具可以发现其他类型的错误。对于sparse，可以警告程序员
-用户空间和内核空间地址之间的混淆、big endian和small endian数量的混合、在需
-要一组位标志的地方传递整数值等等。sparse必须单独安装(如果您的分发服务器没
-有将其打包，可以在 https://sparse.wiki.kernel.org/index.php/Main_page)找到,
+“sparse”静态分析工具可以发现其他类型的错误。sparse可以警告程序员用户空间
+和内核空间地址之间的混淆、大端序与小端序的混淆、在需要一组位标志的地方传递
+整数值等等。sparse必须单独安装(如果您的分发服务器没有将其打包，
+可以在 https://sparse.wiki.kernel.org/index.php/Main_page 找到）,
然后可以通过在make命令中添加“C=1”在代码上运行它。
“Coccinelle”工具 :ref:`http://coccinelle.lip6.fr/ <devtools_coccinelle>`
@@ -221,8 +224,8 @@ scripts/coccinelle目录下已经打包了相当多的内核“语义补丁”
其他类型的可移植性错误最好通过为其他体系结构编译代码来发现。如果没有S/390系统
-或Blackfin开发板，您仍然可以执行编译步骤。可以在以下位置找到一组用于x86系统的
-大型交叉编译器：
+或Blackfin开发板，您仍然可以执行编译步骤。可以在以下位置找到一大堆用于x86系统的
+交叉编译器：
https://www.kernel.org/pub/tools/crosstool/
@@ -233,22 +236,22 @@ scripts/coccinelle目录下已经打包了相当多的内核“语义补丁”
文档通常比内核开发规则更为例外。即便如此，足够的文档将有助于简化将新代码合并
到内核中的过程，使其他开发人员的生活更轻松，并对您的用户有所帮助。在许多情况
-下，文件的添加已基本上成为强制性的。
+下，添加文档已基本上是强制性的。
任何补丁的第一个文档是其关联的变更日志。日志条目应该描述正在解决的问题、解决
方案的形式、处理补丁的人员、对性能的任何相关影响，以及理解补丁可能需要的任何
-其他内容。确保changelog说明了为什么补丁值得应用；大量开发人员未能提供这些信息。
+其他内容。确保变更日志说明了*为什么*补丁值得应用；大量开发者未能提供这些信息。
-任何添加新用户空间界面的代码（包括新的sysfs或/proc文件）都应该包含该界面的
-文档，该文档使用户空间开发人员能够知道他们在使用什么。请参阅
-Documentation/ABI/README，了解如何格式化此文档以及需要提供哪些信息。
+任何添加新用户空间接口的代码——包括新的sysfs或/proc文件——都应该包含该接口
+的文档，该文档使用户空间开发人员能够知道他们在使用什么。请参阅
+Documentation/ABI/README，了解如何此文档格式以及需要提供哪些信息。
-文件 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
-描述了内核的所有引导时间参数。任何添加新参数的补丁都应该向该文件添加适当的
+文档 :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
+描述了内核的所有引导时间参数。任何添加新参数的补丁都应该向该文档添加适当的
条目。
-任何新的配置选项都必须附有帮助文本，帮助文本清楚地解释了这些选项以及用户可能
-希望何时选择它们。
+任何新的配置选项都必须附有帮助文本，帮助文本需清楚地解释这些选项以及用户可能
+希望何时使用它们。
许多子系统的内部API信息通过专门格式化的注释进行记录；这些注释可以通过
“kernel-doc”脚本以多种方式提取和格式化。如果您在具有kerneldoc注释的子系统中
@@ -257,31 +260,31 @@ Documentation/ABI/README，了解如何格式化此文档以及需要提供哪
来说是一个有用的活动。这些注释的格式以及如何创建kerneldoc模板的一些信息可以在
:ref:`Documentation/doc-guide/ <doc_guide>` 上找到。
-任何阅读大量现有内核代码的人都会注意到，注释的缺失往往是最值得注意的。再一次，
-对新代码的期望比过去更高；合并未注释的代码将更加困难。这就是说，人们几乎不希望
-用语言注释代码。代码本身应该是可读的，注释解释了更微妙的方面。
+任何阅读大量现有内核代码的人都会注意到，注释的缺失往往是最值得注意的。同时，
+对新代码的要求比过去更高；合并未注释的代码将更加困难。这就是说，人们并不期望
+详细注释的代码。代码本身应该是自解释的，注释阐释了更微妙的方面。
某些事情应该总是被注释。使用内存屏障时，应附上一行文字，解释为什么需要设置内存
-屏障。数据结构的锁定规则通常需要在某个地方解释。一般来说，主要数据结构需要全面
-的文档。应该指出单独代码位之间不明显的依赖性。任何可能诱使代码看门人进行错误的
-“清理”的事情都需要一个注释来说明为什么要这样做。等等。
+屏障。数据结构的锁规则通常需要在某个地方解释。一般来说，主要数据结构需要全面
+的文档。应该指出代码中分立的位之间不明显的依赖性。任何可能诱使代码管理人进行
+错误的“清理”的事情都需要一个注释来说明为什么要这样做。等等。
内部API更改
-----------
-内核提供给用户空间的二进制接口不能被破坏，除非在最严重的情况下。相反，内核的
-内部编程接口是高度流动的，当需要时可以更改。如果你发现自己不得不处理一个内核
-API，或者仅仅因为它不满足你的需求而不使用特定的功能，这可能是API需要改变的一
-个标志。作为内核开发人员，您有权进行此类更改。
+内核提供给用户空间的二进制接口不能被破坏，除非逼不得已。而内核的内部编程接口
+是高度流动的，当需要时可以更改。如果你发现自己不得不处理一个内核API，或者仅
+仅因为它不满足你的需求导致无法使用特定的功能，这可能是API需要改变的一个标志。
+作为内核开发人员，您有权进行此类更改。
-当然, 可以进行API更改，但它们必须是合理的。因此，任何进行内部API更改的补丁都
-应该附带一个关于更改内容和必要原因的描述。这种变化也应该分解成一个单独的补丁，
-而不是埋在一个更大的补丁中。
+的确可以进行API更改，但更改必须是合理的。因此任何进行内部API更改的补丁都应该
+附带关于更改内容和必要原因的描述。这种变化也应该拆分成一个单独的补丁，而不是
+埋在一个更大的补丁中。
另一个要点是，更改内部API的开发人员通常要负责修复内核树中被更改破坏的任何代码。
-对于一个广泛使用的函数，这个职责可以导致成百上千的变化，其中许多变化可能与其他
-开发人员正在做的工作相冲突。不用说，这可能是一项大工作，所以最好确保理由是
+对于一个广泛使用的函数，这个责任可以导致成百上千的变化，其中许多变化可能与其他
+开发人员正在做的工作相冲突。不用说，这可能是一项大工程，所以最好确保理由是
可靠的。请注意，coccinelle工具可以帮助进行广泛的API更改。
在进行不兼容的API更改时，应尽可能确保编译器捕获未更新的代码。这将帮助您确保找
--
2.20.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v3 6/9] docs/zh_CN: Improve zh_CN/process/5.Posting.rst
2021-03-05 5:25 [PATCH v3 0/9] docs/zh_CN: Improve language in zh_CN/process/ Wu XiangCheng
` (4 preceding siblings ...)
2021-03-05 5:27 ` [PATCH v3 5/9] docs/zh_CN: Improve zh_CN/process/4.Coding.rst Wu XiangCheng
@ 2021-03-05 5:27 ` Wu XiangCheng
2021-03-05 8:49 ` Alex Shi
2021-03-05 5:28 ` [PATCH v3 7/9] docs/zh_CN: Improve zh_CN/process/6.Followthrough Wu XiangCheng
` (3 subsequent siblings)
9 siblings, 1 reply; 12+ messages in thread
From: Wu XiangCheng @ 2021-03-05 5:27 UTC (permalink / raw)
To: alex.shi; +Cc: corbet, linux-doc
Improve language and grammar of zh_CN/process/5.Posting.rst
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
---
.../translations/zh_CN/process/5.Posting.rst | 243 +++++++++---------
1 file changed, 125 insertions(+), 118 deletions(-)
diff --git a/Documentation/translations/zh_CN/process/5.Posting.rst b/Documentation/translations/zh_CN/process/5.Posting.rst
index 9ff9945f918c..b0c65614844d 100644
--- a/Documentation/translations/zh_CN/process/5.Posting.rst
+++ b/Documentation/translations/zh_CN/process/5.Posting.rst
@@ -1,150 +1,157 @@
.. include:: ../disclaimer-zh_CN.rst
:Original: :ref:`Documentation/process/5.Posting.rst <development_posting>`
-:Translator: Alex Shi <alex.shi@linux.alibaba.com>
+
+:Translator:
+
+ 时奎亮 Alex Shi <alex.shi@linux.alibaba.com>
+
+:校译:
+
+ 吴想成 Wu XiangCheng <bobwxc@email.cn>
.. _cn_development_posting:
发布补丁
========
-迟早，当您的工作准备好提交给社区进行审查，并最终包含到主线内核中时。不出所料，
+您的工作迟早会准备好提交给社区进行审查，并最终包含到主线内核中。毫不稀奇，
内核开发社区已经发展出一套用于发布补丁的约定和过程；遵循这些约定和过程将使
-参与其中的每个人的生活更加轻松。本文件将试图合理详细地涵盖这些期望；更多信息
-也可在以下文件中找到
-:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`,
-:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
-和 :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`.
+参与其中的每个人的生活更加轻松。本文档试图描述这些约定的部分细节；更多信息
+也可在以下文档中找到
+:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`，
+:ref:`Documentation/translations/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>`
+和 :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`。
何时邮寄
--------
-在补丁完全“准备好”之前，有一个不断的诱惑来避免发布补丁。对于简单的补丁，
-这不是问题。但是，如果正在完成的工作很复杂，那么在工作完成之前从社区获得
-反馈就可以获得很多好处。因此，您应该考虑发布正在进行的工作，甚至使Git树
-可用，以便感兴趣的开发人员可以随时赶上您的工作。
+在补丁完全“准备好”之前，避免发布补丁是一种持续的诱惑。对于简单的补丁，这
+不是问题。但是如果正在完成的工作很复杂，那么在工作完成之前从社区获得反馈就
+可以获得很多好处。因此，您应该考虑发布正在进行的工作，甚至维护一个可用的Git
+树，以便感兴趣的开发人员可以随时赶上您的工作。
-当发布还没有准备好包含的代码时，最好在发布本身中这样说。还应提及任何有待完成
-的主要工作和任何已知问题。很少有人会看到那些被认为是半生不熟的补丁，但是那些
-人会想到他们可以帮助你把工作推向正确的方向。
+当发布中有尚未准备好被包含的代码，最好在发布中说明。还应提及任何有待完成的
+主要工作和任何已知问题。很少有人会愿意看那些被认为是半生不熟的补丁，但是
+那些愿意的人会带着他们的点子来一起帮助你把工作推向正确的方向。
创建补丁之前
------------
-在考虑将补丁发送到开发社区之前，有许多事情应该做。这些包括：
+在考虑将补丁发送到开发社区之前，有许多事情应该做。包括：
- - 尽可能地测试代码。利用内核的调试工具，确保内核使用所有合理的配置选项组合
- 进行构建，使用跨编译器为不同的体系结构进行构建等。
+ - 尽可能地测试代码。利用内核的调试工具，确保内核使用了所有可能的配置选项组合
+ 进行构建，使用交叉编译器为不同的体系结构进行构建等。
- - 确保您的代码符合内核编码风格指南。
+ - 确保您的代码符合内核代码风格指南。
- 您的更改是否具有性能影响？如果是这样，您应该运行基准测试来显示您的变更的
影响（或好处）；结果的摘要应该包含在补丁中。
- 确保您有权发布代码。如果这项工作是为雇主完成的，雇主对这项工作具有所有权，
- 并且必须同意根据GPL对其进行放行。
+ 并且必须同意根据GPL对其进行发布。
一般来说，在发布代码之前进行一些额外的思考，几乎总是能在短时间内得到回报。
补丁准备
--------
-准备发布补丁可能是一个惊人的工作量，但再次尝试节省时间在这里通常是不明智的，
-即使在短期内。
+准备补丁发布的工作量可能很惊人，但在此尝试节省时间通常是不明智的，即使在短期
+内亦然。
-必须针对内核的特定版本准备补丁。作为一般规则，补丁程序应该基于Linus的Git树中
-的当前主线。当以主线为基础时，从一个众所周知的发布点开始——一个稳定的或RC的
-发布——而不是在一个主线分支任意点。
+必须针对内核的特定版本准备补丁。一般来说，补丁应该基于Linus的Git树中的当前
+主线。当以主线为基础时，请从一个众所周知的发布点开始——如稳定版本或 -rc
+版本发布点——而不是在一个任意的主线分支点。
-但是，可能需要针对-mm、linux-next或子系统树生成版本，以便于更广泛的测试和审查。
-根据补丁的区域以及其他地方的情况，针对这些其他树建立补丁可能需要大量的工作来
+也可能需要针对-mm、linux-next或子系统树生成版本，以便于更广泛的测试和审查。
+根据补丁的区域以及其他地方的情况，针对其他树建立的补丁可能需要大量的工作来
解决冲突和处理API更改。
只有最简单的更改才应格式化为单个补丁；其他所有更改都应作为一系列逻辑更改进行。
分割补丁是一门艺术；一些开发人员花了很长时间来弄清楚如何按照社区期望的方式来
-做。然而，有一些经验法则可以大大帮助：
+分割。不过，这些经验法则也许有帮助：
- - 您发布的补丁程序系列几乎肯定不会是工作系统中的一系列更改。相反，您所做的
- 更改需要在最终形式中加以考虑，然后以有意义的方式进行拆分。开发人员对离散的、
- 自包含的更改感兴趣，而不是您获取这些更改的路径。
+ - 您发布的补丁系列几乎肯定不会是开发过程中版本控制系统中的一系列更改。相反，
+ 需要对您所做更改的最终形式加以考虑，然后以有意义的方式进行拆分。开发人员对
+ 离散的、自包含的更改感兴趣，而不是您创造这些更改的原始路径。
- - 每个逻辑上独立的变更都应该格式化为单独的补丁。这些更改可以是小的（“向此
- 结构添加字段”）或大的（例如，添加一个重要的新驱动程序），但它们在概念上
- 应该是小的，并且可以接受一行描述。每个补丁都应该做一个特定的更改，可以单独
- 检查并验证它所做的事情。
+ - 每个逻辑上独立的变更都应该格式化为单独的补丁。这些更改可以是小的（如“向
+ 此结构体添加字段”）或大的（如添加一个重要的新驱动程序），但它们在概念上
+ 应该是小的，并且可以在一行内简述。每个补丁都应该做一个特定的、可以单独
+ 检查并验证它所做的事情的更改。
- - 作为重申上述准则的一种方法：不要在同一补丁中混合不同类型的更改。如果一个
- 补丁修复了一个关键的安全漏洞，重新排列了一些结构，并重新格式化了代码，那么
- 很有可能它会被忽略，而重要的修复将丢失。
+ - 换种方式重申上述准则，也就是说：不要在同一补丁中混合不同类型的更改。如果
+ 一个补丁修复了一个关键的安全漏洞，又重新排列了一些结构，还重新格式化了代
+ 码，那么它很有可能会被忽略，从而导致重要的修复丢失。
- - 每个补丁都应该产生一个内核，它可以正确地构建和运行；如果补丁系列在中间被
- 中断，那么结果应该仍然是一个工作的内核。补丁系列的部分应用是使用
- “git bisct”工具查找回归的一个常见场景；如果结果是一个损坏的内核，那么对于
- 那些从事追踪问题的高尚工作的开发人员和用户来说，将使他们的生活更加艰难。
+ - 每个补丁都应该能创建一个可以正确地构建和运行的内核；如果补丁系列在中间被
+ 断开，那么结果仍应是一个正常工作的内核。部分应用一系列补丁是使用
+ “git bisct”工具查找回归的一个常见场景；如果结果是一个损坏的内核，那么将使
+ 那些从事追踪问题的高尚工作的开发人员和用户的生活更加艰难。
- - 不过，不要过分。一位开发人员曾经将一组编辑内容作为500个单独的补丁发布到一个
- 文件中，这并没有使他成为内核邮件列表中最受欢迎的人。一个补丁可以相当大，
- 只要它仍然包含一个单一的逻辑变更。
+ - 不要过分分割。一位开发人员曾经将一组针对单个文件的编辑分成500个单独的补丁
+ 发布，这并没有使他成为内核邮件列表中最受欢迎的人。一个补丁可以相当大，
+ 只要它仍然包含一个单一的 *逻辑* 变更。
- - 用一系列补丁添加一个全新的基础设施是很有诱惑力的，但是在系列中的最后一个
- 补丁启用整个补丁之前，该基础设施是不使用的。如果可能的话，应该避免这种
- 诱惑；如果这个系列增加了回归，那么二分法将指出最后一个补丁是导致问题的
- 补丁，即使真正的bug在其他地方。只要有可能，添加新代码的补丁程序应该立即
- 激活该代码。
+ - 用一系列补丁添加一个全新的基础设施，但是该设施在系列中的最后一个补丁启用
+ 整个变更之前不能使用，这看起来很诱人。如果可能的话，应该避免这种诱惑；
+ 如果这个系列增加了回归，那么二分法将指出最后一个补丁是导致问题的补丁，
+ 即使真正的bug在其他地方。只要有可能，添加新代码的补丁程序应该立即激活该
+ 代码。
-创建完美补丁系列的工作可能是一个令人沮丧的过程，在完成“真正的工作”之后需要花费
-大量的时间和思考。但是，如果做得好，这是一段很好的时间。
+创建完美补丁系列的工作可能是一个令人沮丧的过程，在完成“真正的工作”之后需要
+花费大量的时间和思考。但是如果做得好，花费的时间就是值得的。
补丁格式和更改日志
------------------
所以现在你有了一系列完美的补丁可以发布，但是这项工作还没有完成。每个补丁都
-需要被格式化成一条消息，它可以快速而清晰地将其目的传达给世界其他地方。为此，
+需要被格式化成一条消息，以快速而清晰地将其目的传达到世界其他地方。为此，
每个补丁将由以下部分组成：
- - 命名补丁作者的可选“from”行。只有当你通过电子邮件传递别人的补丁时，这一行
- 才是必要的，但是如果有疑问，添加它不会有任何伤害。
+ - 可选的“From”行，表明补丁作者。只有当你通过电子邮件发送别人的补丁时，这一行
+ 才是必须的，但是为防止疑问加上它也不会有什么坏处。
- - 一行描述补丁的作用。对于没有其他上下文的读者来说，此消息应该足够了解补丁
- 的范围；这是将在“短格式”变更日志中显示的行。此消息通常首先用相关的子系统
- 名称格式化，然后是补丁的目的。例如：
+ - 一行描述，说明补丁的作用。对于在没有其他上下文的情况下看到该消息的读者来说，
+ 该消息应足以确定修补程序的范围；此行将显示在“short form（简短格式）”变更
+ 日志中。此消息通常需要先加上子系统名称前缀，然后是补丁的目的。例如：
- ::
+ ::
- gpio: fix build on CONFIG_GPIO_SYSFS=n
+ gpio: fix build on CONFIG_GPIO_SYSFS=n
- - 一个空白行，后面是补丁内容的详细描述。这个描述可以是必需的；它应该说明补丁
+ - 一行空白，后接补丁内容的详细描述。此描述可以是任意需要的长度；它应该说明补丁
的作用以及为什么它应该应用于内核。
- - 一个或多个标记行，至少有一个由补丁作者的：signed-off-by 签名。签名将在下面
- 更详细地描述。
+ - 一个或多个标记行，至少有一个由补丁作者的 Signed-off-by 签名。标记将在下面
+ 详细描述。
-上面的项目一起构成补丁的变更日志。写一篇好的变更日志是一门至关重要但常常被
-忽视的艺术；值得花一点时间来讨论这个问题。当你写一个变更日志时，你应该记住
-有很多不同的人会读你的话。其中包括子系统维护人员和审查人员，他们需要决定是否
-应该包括补丁，分销商和其他维护人员试图决定是否应该将补丁反向移植到其他内核，
-bug搜寻人员想知道补丁是否负责他们正在追查的问题，想知道内核如何变化的用户。
-等等。一个好的变更日志以最直接和最简洁的方式向所有这些人传达所需的信息。
+上面的项目一起构成补丁的变更日志。写一则好的变更日志是一门至关重要但常常被
+忽视的艺术；值得花一点时间来讨论这个问题。当你编写变更日志时，你应该记住有
+很多不同的人会读你的话。其中包括子系统维护人员和审查人员，他们需要决定是否
+应该合并补丁，分销商和其他维护人员试图决定是否应该将补丁反向移植到其他内核，
+缺陷搜寻人员想知道补丁是否导致他们正在追查的问题，以及想知道内核如何变化的
+用户等等。一个好的变更日志以最直接和最简洁的方式向所有这些人传达所需的信息。
-为此，总结行应该描述变更的影响和动机，以及在一行约束条件下可能发生的变化。
+在结尾，总结行应该描述变更的影响和动机，以及在一行约束条件下可能发生的变化。
然后，详细的描述可以详述这些主题，并提供任何需要的附加信息。如果补丁修复了
-一个bug，请引用引入该bug的commit（如果可能，请在引用commits时同时提供commit id
-和标题）。如果某个问题与特定的日志或编译器输出相关联，请包含该输出以帮助其他
-人搜索同一问题的解决方案。如果更改是为了支持以后补丁中的其他更改，那么就这么
-说。如果更改了内部API，请详细说明这些更改以及其他开发人员应该如何响应。一般
-来说，你越能把自己放在每个阅读你的changelog的人的位置上，changelog（和内核
+一个缺陷，请引用引入该缺陷的提交（如果可能，请在引用提交时同时提供其 id 和
+标题）。如果某个问题与特定的日志或编译器输出相关联，请包含该输出以帮助其他
+人搜索同一问题的解决方案。如果更改是为了支持以后补丁中的其他更改，那么应当
+说明。如果更改了内部API，请详细说明这些更改以及其他开发人员应该如何响应。
+一般来说，你越把自己放在每个阅读你变更日志的人的位置上，变更日志（和内核
作为一个整体）就越好。
-不用说，变更日志应该是将变更提交到修订控制系统时使用的文本。接下来是：
+不消说，变更日志是将变更提交到版本控制系统时使用的文本。接下来将是：
- - 补丁本身，采用统一的（“-u”）补丁格式。将“-p”选项用于diff将使函数名与更改
- 相关联，从而使结果补丁更容易被其他人读取。
+ - 补丁本身，采用统一的（“-u”）补丁格式。使用“-p”选项来diff将使函数名与
+ 更改相关联，从而使结果补丁更容易被其他人读取。
-您应该避免在补丁中包括对不相关文件（例如，由构建过程生成的文件或编辑器
-备份文件）的更改。文档目录中的文件“dontdiff”在这方面有帮助；使用“-X”选项将
+您应该避免在补丁中包括与更改不相关文件（例如，构建过程生成的文件或编辑器
+备份文件）。文档目录中的“dontdiff”文件在这方面有帮助；使用“-X”选项将
其传递给diff。
-上面提到的标签用于描述各种开发人员如何与这个补丁的开发相关联。
+上面提到的标签（tag）用于描述各种开发人员如何与这个补丁的开发相关联。
:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
文档中对它们进行了详细描述；下面是一个简短的总结。每一行的格式如下：
@@ -154,87 +161,87 @@ bug搜寻人员想知道补丁是否负责他们正在追查的问题，想知
常用的标签有：
- - Signed-off-by: 这是一个开发人员的证明，他或她有权提交补丁以包含到内核中。
- 这是开发来源认证协议，其全文可在
+ - Signed-off-by: 这是一个开发人员的证明，证明他或她有权提交补丁以包含到内核
+ 中。这表明同意开发者来源认证协议，其全文见
:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
- 中找到，如果没有适当的签字，则不能合并到主线中。
+ 如果没有合适的签字，则不能合并到主线中。
- Co-developed-by: 声明补丁是由多个开发人员共同创建的；当几个人在一个补丁上
- 工作时，它用于将属性赋予共同作者（除了 From: 所赋予的作者之外）。因为
- Co-developed-by: 表示作者身份，所以每个共同开发人, 必须紧跟在相关合作作者
- 的签名之后。具体内容和示例可以在以下文件中找到
+ 工作时，它用于给出共同作者（除了 From: 所给出的作者之外）。由于
+ Co-developed-by: 表示作者身份，所以每个共同开发人，必须紧跟在相关合作作者
+ 的Signed-off-by之后。具体内容和示例见以下文件
:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
- Acked-by: 表示另一个开发人员（通常是相关代码的维护人员）同意补丁适合包含
在内核中。
- - Tested-by: 声明指定的人已经测试了补丁并发现它可以工作。
+ - Tested-by: 声明某人已经测试了补丁并确认它可以工作。
- - Reviewed-by: 指定的开发人员已经审查了补丁的正确性；有关详细信息，请参阅
+ - Reviewed-by: 表示某开发人员已经审查了补丁的正确性；有关详细信息，请参阅
:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
- - Reported-by: 指定报告此补丁修复的问题的用户；此标记用于提供感谢。
+ - Reported-by: 指定报告此补丁修复的问题的用户；此标记用于表示感谢。
- - Cc：指定的人收到了补丁的副本，并有机会对此发表评论。
+ - Cc：指定某人收到了补丁的副本，并有机会对此发表评论。
-在补丁中添加标签时要小心：只有cc:才适合在没有指定人员明确许可的情况下添加。
+在补丁中添加标签时要小心：只有Cc:才适合在没有指定人员明确许可的情况下添加。
发送补丁
--------
-在邮寄补丁之前，您还需要注意以下几点：
+在寄出补丁之前，您还需要注意以下几点：
- - 您确定您的邮件发送程序不会损坏补丁吗？有免费的空白更改或由邮件客户端
- 执行的行包装的补丁不会在另一端复原，并且通常不会进行任何详细检查。如果有
- 任何疑问，把补丁寄给你自己，让你自己相信它是完好无损的。
+ - 您确定您的邮件发送程序不会损坏补丁吗？被邮件客户端更改空白或修饰了行的补丁
+ 无法被另一端接受，并且通常不会进行任何详细检查。如果有任何疑问，先把补丁寄
+ 给你自己，让你自己确定它是完好无损的。
:ref:`Documentation/translations/zh_CN/process/email-clients.rst <cn_email_clients>`
- 提供了一些有用的提示，可以让特定的邮件客户机工作以发送补丁。
+ 提供了一些有用的提示，可以让特定的邮件客户端正常发送补丁。
- - 你确定你的补丁没有愚蠢的错误吗？您应该始终通过scripts/checkpatch.pl运行
- 补丁程序，并解决它提出的投诉。请记住，checkpatch.pl虽然是大量思考内核
- 补丁应该是什么样子的体现，但它并不比您聪明。如果修复checkpatch.pl投诉会
+ - 你确定你的补丁没有荒唐的错误吗？您应该始终通过scripts/checkpatch.pl检查
+ 补丁程序，并解决它提出的问题。请记住，checkpatch.pl，虽然体现了对内核补丁
+ 应该是什么样的大量思考，但它并不比您聪明。如果修复checkpatch.pl给的问题会
使代码变得更糟，请不要这样做。
补丁应始终以纯文本形式发送。请不要将它们作为附件发送；这使得审阅者在答复中更难
引用补丁的部分。相反，只需将补丁直接放到您的消息中。
-邮寄补丁时，重要的是将副本发送给任何可能感兴趣的人。与其他一些项目不同，内核
-鼓励人们错误地发送过多的副本；不要假定相关人员会看到您在邮件列表中的发布。
+寄出补丁时，重要的是将副本发送给任何可能感兴趣的人。与其他一些项目不同，内核
+鼓励人们甚至错误地发送过多的副本；不要假定相关人员会看到您在邮件列表中的发布。
尤其是，副本应发送至：
- - 受影响子系统的维护人员。如前所述，维护人员文件是查找这些人员的第一个地方。
+ - 受影响子系统的维护人员。如前所述，维护人员文件是查找这些人员的首选地方。
- 其他在同一领域工作的开发人员，尤其是那些现在可能在那里工作的开发人员。使用
git查看还有谁修改了您正在处理的文件，这很有帮助。
- - 如果您对错误报告或功能请求做出响应，也可以抄送原始发送人。
+ - 如果您对某错误报告或功能请求做出响应，也可以抄送原始发送人。
- - 将副本发送到相关邮件列表，或者，如果没有其他应用，则发送到Linux内核列表。
+ - 将副本发送到相关邮件列表，或者若无相关列表，则发送到linux-kernel列表。
- - 如果您正在修复一个bug，请考虑该修复是否应进入下一个稳定更新。如果是这样，
- stable@vger.kernel.org 应该得到补丁的副本。另外，在补丁本身的标签中添加
- 一个“cc:stable@vger.kernel.org”；这将使稳定团队在修复进入主线时收到通知。
+ - 如果您正在修复一个缺陷，请考虑该修复是否应进入下一个稳定更新。如果是这样，
+ 补丁副本也应发到stable@vger.kernel.org 。另外，在补丁本身的标签中添加一个
+ “Cc: stable@vger.kernel.org”；这将使稳定版团队在修复进入主线时收到通知。
-当为一个补丁选择接收者时，最好知道你认为谁最终会接受这个补丁并将其合并。虽然
-可以将补丁直接发送给LinusTorvalds并让他合并，但通常情况下不会这样做。Linus
-很忙，并且有子系统维护人员负责监视内核的特定部分。通常您会希望维护人员合并您
-的补丁。如果没有明显的维护人员，Andrew Morton通常是最后的补丁目标。
+当为一个补丁选择接收者时，最好清楚你认为谁最终会接受这个补丁并将其合并。虽然
+可以将补丁直接发给Linus Torvalds并让他合并，但通常情况下不会这样做。Linus很
+忙，并且有子系统维护人员负责监视内核的特定部分。通常您会希望维护人员合并您的
+补丁。如果没有明显的维护人员，Andrew Morton通常是最后的补丁接收者。
-补丁需要好的主题行。补丁程序行的规范格式如下：
+补丁需要好的主题行。补丁主题行的规范格式如下：
::
[PATCH nn/mm] subsys: one-line description of the patch
-其中“nn”是补丁的序号，“mm”是系列中补丁的总数，“subsys”是受影响子系统的名称。
-显然，一个单独的补丁可以省略nn/mm。
+其中“nn”是补丁的序号，“mm”是系列中补丁的总数，“subsys”是受影响子系统的
+名称。当然，一个单独的补丁可以省略nn/mm。
-如果您有一系列重要的补丁，那么通常将介绍性描述作为零部分发送。不过，这种约定
-并没有得到普遍遵循；如果您使用它，请记住简介中的信息不会使它进入内核变更日志。
+如果您有一系列重要的补丁，那么通常发送一个简介作为第〇部分。不过，这个约定
+并没有得到普遍遵循；如果您使用它，请记住简介中的信息不会进入内核变更日志。
因此，请确保补丁本身具有完整的变更日志信息。
一般来说，多部分补丁的第二部分和后续部分应作为对第一部分的回复发送，以便它们
在接收端都连接在一起。像git和coilt这样的工具有命令，可以通过适当的线程发送
-一组补丁。但是，如果您有一个长系列，并且正在使用git，请远离–chain reply-to
-选项，以避免创建异常深的嵌套。
+一组补丁。但是，如果您有一长串补丁，并正使用git，请不要使用–-chain-reply-to
+选项，以避免创建过深的嵌套。
--
2.20.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* Re: [PATCH v3 6/9] docs/zh_CN: Improve zh_CN/process/5.Posting.rst
2021-03-05 5:27 ` [PATCH v3 6/9] docs/zh_CN: Improve zh_CN/process/5.Posting.rst Wu XiangCheng
@ 2021-03-05 8:49 ` Alex Shi
0 siblings, 0 replies; 12+ messages in thread
From: Alex Shi @ 2021-03-05 8:49 UTC (permalink / raw)
To: Wu XiangCheng; +Cc: corbet, linux-doc
在 2021/3/5 下午1:27, Wu XiangCheng 写道:
> Improve language and grammar of zh_CN/process/5.Posting.rst
>
> Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
> Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
Hi XiangCheng,
Thanks for the polishing!
When I try to give me Reviewed-by for patch 5~9. I found you pick it up
for them. Please don't do such assumption next time.
Thanks
Alex
> ---
> .../translations/zh_CN/process/5.Posting.rst | 243 +++++++++---------
> 1 file changed, 125 insertions(+), 118 deletions(-)
>
> diff --git a/Documentation/translations/zh_CN/process/5.Posting.rst b/Documentation/translations/zh_CN/process/5.Posting.rst
> index 9ff9945f918c..b0c65614844d 100644
> --- a/Documentation/translations/zh_CN/process/5.Posting.rst
> +++ b/Documentation/translations/zh_CN/process/5.Posting.rst
> @@ -1,150 +1,157 @@
> .. include:: ../disclaimer-zh_CN.rst
>
> :Original: :ref:`Documentation/process/5.Posting.rst <development_posting>`
> -:Translator: Alex Shi <alex.shi@linux.alibaba.com>
> +
> +:Translator:
> +
> + 时奎亮 Alex Shi <alex.shi@linux.alibaba.com>
> +
> +:校译:
> +
> + 吴想成 Wu XiangCheng <bobwxc@email.cn>
>
> .. _cn_development_posting:
>
> 发布补丁
> ========
>
> -迟早，当您的工作准备好提交给社区进行审查，并最终包含到主线内核中时。不出所料，
> +您的工作迟早会准备好提交给社区进行审查，并最终包含到主线内核中。毫不稀奇，
> 内核开发社区已经发展出一套用于发布补丁的约定和过程；遵循这些约定和过程将使
> -参与其中的每个人的生活更加轻松。本文件将试图合理详细地涵盖这些期望；更多信息
> -也可在以下文件中找到
> -:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`,
> -:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
> -和 :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`.
> +参与其中的每个人的生活更加轻松。本文档试图描述这些约定的部分细节；更多信息
> +也可在以下文档中找到
> +:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`，
> +:ref:`Documentation/translations/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>`
> +和 :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`。
>
> 何时邮寄
> --------
>
> -在补丁完全“准备好”之前，有一个不断的诱惑来避免发布补丁。对于简单的补丁，
> -这不是问题。但是，如果正在完成的工作很复杂，那么在工作完成之前从社区获得
> -反馈就可以获得很多好处。因此，您应该考虑发布正在进行的工作，甚至使Git树
> -可用，以便感兴趣的开发人员可以随时赶上您的工作。
> +在补丁完全“准备好”之前，避免发布补丁是一种持续的诱惑。对于简单的补丁，这
> +不是问题。但是如果正在完成的工作很复杂，那么在工作完成之前从社区获得反馈就
> +可以获得很多好处。因此，您应该考虑发布正在进行的工作，甚至维护一个可用的Git
> +树，以便感兴趣的开发人员可以随时赶上您的工作。
>
> -当发布还没有准备好包含的代码时，最好在发布本身中这样说。还应提及任何有待完成
> -的主要工作和任何已知问题。很少有人会看到那些被认为是半生不熟的补丁，但是那些
> -人会想到他们可以帮助你把工作推向正确的方向。
> +当发布中有尚未准备好被包含的代码，最好在发布中说明。还应提及任何有待完成的
> +主要工作和任何已知问题。很少有人会愿意看那些被认为是半生不熟的补丁，但是
> +那些愿意的人会带着他们的点子来一起帮助你把工作推向正确的方向。
>
> 创建补丁之前
> ------------
>
> -在考虑将补丁发送到开发社区之前，有许多事情应该做。这些包括：
> +在考虑将补丁发送到开发社区之前，有许多事情应该做。包括：
>
> - - 尽可能地测试代码。利用内核的调试工具，确保内核使用所有合理的配置选项组合
> - 进行构建，使用跨编译器为不同的体系结构进行构建等。
> + - 尽可能地测试代码。利用内核的调试工具，确保内核使用了所有可能的配置选项组合
> + 进行构建，使用交叉编译器为不同的体系结构进行构建等。
>
> - - 确保您的代码符合内核编码风格指南。
> + - 确保您的代码符合内核代码风格指南。
>
> - 您的更改是否具有性能影响？如果是这样，您应该运行基准测试来显示您的变更的
> 影响（或好处）；结果的摘要应该包含在补丁中。
>
> - 确保您有权发布代码。如果这项工作是为雇主完成的，雇主对这项工作具有所有权，
> - 并且必须同意根据GPL对其进行放行。
> + 并且必须同意根据GPL对其进行发布。
>
> 一般来说，在发布代码之前进行一些额外的思考，几乎总是能在短时间内得到回报。
>
> 补丁准备
> --------
>
> -准备发布补丁可能是一个惊人的工作量，但再次尝试节省时间在这里通常是不明智的，
> -即使在短期内。
> +准备补丁发布的工作量可能很惊人，但在此尝试节省时间通常是不明智的，即使在短期
> +内亦然。
>
> -必须针对内核的特定版本准备补丁。作为一般规则，补丁程序应该基于Linus的Git树中
> -的当前主线。当以主线为基础时，从一个众所周知的发布点开始——一个稳定的或RC的
> -发布——而不是在一个主线分支任意点。
> +必须针对内核的特定版本准备补丁。一般来说，补丁应该基于Linus的Git树中的当前
> +主线。当以主线为基础时，请从一个众所周知的发布点开始——如稳定版本或 -rc
> +版本发布点——而不是在一个任意的主线分支点。
>
> -但是，可能需要针对-mm、linux-next或子系统树生成版本，以便于更广泛的测试和审查。
> -根据补丁的区域以及其他地方的情况，针对这些其他树建立补丁可能需要大量的工作来
> +也可能需要针对-mm、linux-next或子系统树生成版本，以便于更广泛的测试和审查。
> +根据补丁的区域以及其他地方的情况，针对其他树建立的补丁可能需要大量的工作来
> 解决冲突和处理API更改。
>
> 只有最简单的更改才应格式化为单个补丁；其他所有更改都应作为一系列逻辑更改进行。
> 分割补丁是一门艺术；一些开发人员花了很长时间来弄清楚如何按照社区期望的方式来
> -做。然而，有一些经验法则可以大大帮助：
> +分割。不过，这些经验法则也许有帮助：
>
> - - 您发布的补丁程序系列几乎肯定不会是工作系统中的一系列更改。相反，您所做的
> - 更改需要在最终形式中加以考虑，然后以有意义的方式进行拆分。开发人员对离散的、
> - 自包含的更改感兴趣，而不是您获取这些更改的路径。
> + - 您发布的补丁系列几乎肯定不会是开发过程中版本控制系统中的一系列更改。相反，
> + 需要对您所做更改的最终形式加以考虑，然后以有意义的方式进行拆分。开发人员对
> + 离散的、自包含的更改感兴趣，而不是您创造这些更改的原始路径。
>
> - - 每个逻辑上独立的变更都应该格式化为单独的补丁。这些更改可以是小的（“向此
> - 结构添加字段”）或大的（例如，添加一个重要的新驱动程序），但它们在概念上
> - 应该是小的，并且可以接受一行描述。每个补丁都应该做一个特定的更改，可以单独
> - 检查并验证它所做的事情。
> + - 每个逻辑上独立的变更都应该格式化为单独的补丁。这些更改可以是小的（如“向
> + 此结构体添加字段”）或大的（如添加一个重要的新驱动程序），但它们在概念上
> + 应该是小的，并且可以在一行内简述。每个补丁都应该做一个特定的、可以单独
> + 检查并验证它所做的事情的更改。
>
> - - 作为重申上述准则的一种方法：不要在同一补丁中混合不同类型的更改。如果一个
> - 补丁修复了一个关键的安全漏洞，重新排列了一些结构，并重新格式化了代码，那么
> - 很有可能它会被忽略，而重要的修复将丢失。
> + - 换种方式重申上述准则，也就是说：不要在同一补丁中混合不同类型的更改。如果
> + 一个补丁修复了一个关键的安全漏洞，又重新排列了一些结构，还重新格式化了代
> + 码，那么它很有可能会被忽略，从而导致重要的修复丢失。
>
> - - 每个补丁都应该产生一个内核，它可以正确地构建和运行；如果补丁系列在中间被
> - 中断，那么结果应该仍然是一个工作的内核。补丁系列的部分应用是使用
> - “git bisct”工具查找回归的一个常见场景；如果结果是一个损坏的内核，那么对于
> - 那些从事追踪问题的高尚工作的开发人员和用户来说，将使他们的生活更加艰难。
> + - 每个补丁都应该能创建一个可以正确地构建和运行的内核；如果补丁系列在中间被
> + 断开，那么结果仍应是一个正常工作的内核。部分应用一系列补丁是使用
> + “git bisct”工具查找回归的一个常见场景；如果结果是一个损坏的内核，那么将使
> + 那些从事追踪问题的高尚工作的开发人员和用户的生活更加艰难。
>
> - - 不过，不要过分。一位开发人员曾经将一组编辑内容作为500个单独的补丁发布到一个
> - 文件中，这并没有使他成为内核邮件列表中最受欢迎的人。一个补丁可以相当大，
> - 只要它仍然包含一个单一的逻辑变更。
> + - 不要过分分割。一位开发人员曾经将一组针对单个文件的编辑分成500个单独的补丁
> + 发布，这并没有使他成为内核邮件列表中最受欢迎的人。一个补丁可以相当大，
> + 只要它仍然包含一个单一的 *逻辑* 变更。
>
> - - 用一系列补丁添加一个全新的基础设施是很有诱惑力的，但是在系列中的最后一个
> - 补丁启用整个补丁之前，该基础设施是不使用的。如果可能的话，应该避免这种
> - 诱惑；如果这个系列增加了回归，那么二分法将指出最后一个补丁是导致问题的
> - 补丁，即使真正的bug在其他地方。只要有可能，添加新代码的补丁程序应该立即
> - 激活该代码。
> + - 用一系列补丁添加一个全新的基础设施，但是该设施在系列中的最后一个补丁启用
> + 整个变更之前不能使用，这看起来很诱人。如果可能的话，应该避免这种诱惑；
> + 如果这个系列增加了回归，那么二分法将指出最后一个补丁是导致问题的补丁，
> + 即使真正的bug在其他地方。只要有可能，添加新代码的补丁程序应该立即激活该
> + 代码。
>
> -创建完美补丁系列的工作可能是一个令人沮丧的过程，在完成“真正的工作”之后需要花费
> -大量的时间和思考。但是，如果做得好，这是一段很好的时间。
> +创建完美补丁系列的工作可能是一个令人沮丧的过程，在完成“真正的工作”之后需要
> +花费大量的时间和思考。但是如果做得好，花费的时间就是值得的。
>
> 补丁格式和更改日志
> ------------------
>
> 所以现在你有了一系列完美的补丁可以发布，但是这项工作还没有完成。每个补丁都
> -需要被格式化成一条消息，它可以快速而清晰地将其目的传达给世界其他地方。为此，
> +需要被格式化成一条消息，以快速而清晰地将其目的传达到世界其他地方。为此，
> 每个补丁将由以下部分组成：
>
> - - 命名补丁作者的可选“from”行。只有当你通过电子邮件传递别人的补丁时，这一行
> - 才是必要的，但是如果有疑问，添加它不会有任何伤害。
> + - 可选的“From”行，表明补丁作者。只有当你通过电子邮件发送别人的补丁时，这一行
> + 才是必须的，但是为防止疑问加上它也不会有什么坏处。
>
> - - 一行描述补丁的作用。对于没有其他上下文的读者来说，此消息应该足够了解补丁
> - 的范围；这是将在“短格式”变更日志中显示的行。此消息通常首先用相关的子系统
> - 名称格式化，然后是补丁的目的。例如：
> + - 一行描述，说明补丁的作用。对于在没有其他上下文的情况下看到该消息的读者来说，
> + 该消息应足以确定修补程序的范围；此行将显示在“short form（简短格式）”变更
> + 日志中。此消息通常需要先加上子系统名称前缀，然后是补丁的目的。例如：
>
> - ::
> + ::
>
> - gpio: fix build on CONFIG_GPIO_SYSFS=n
> + gpio: fix build on CONFIG_GPIO_SYSFS=n
>
> - - 一个空白行，后面是补丁内容的详细描述。这个描述可以是必需的；它应该说明补丁
> + - 一行空白，后接补丁内容的详细描述。此描述可以是任意需要的长度；它应该说明补丁
> 的作用以及为什么它应该应用于内核。
>
> - - 一个或多个标记行，至少有一个由补丁作者的：signed-off-by 签名。签名将在下面
> - 更详细地描述。
> + - 一个或多个标记行，至少有一个由补丁作者的 Signed-off-by 签名。标记将在下面
> + 详细描述。
>
> -上面的项目一起构成补丁的变更日志。写一篇好的变更日志是一门至关重要但常常被
> -忽视的艺术；值得花一点时间来讨论这个问题。当你写一个变更日志时，你应该记住
> -有很多不同的人会读你的话。其中包括子系统维护人员和审查人员，他们需要决定是否
> -应该包括补丁，分销商和其他维护人员试图决定是否应该将补丁反向移植到其他内核，
> -bug搜寻人员想知道补丁是否负责他们正在追查的问题，想知道内核如何变化的用户。
> -等等。一个好的变更日志以最直接和最简洁的方式向所有这些人传达所需的信息。
> +上面的项目一起构成补丁的变更日志。写一则好的变更日志是一门至关重要但常常被
> +忽视的艺术；值得花一点时间来讨论这个问题。当你编写变更日志时，你应该记住有
> +很多不同的人会读你的话。其中包括子系统维护人员和审查人员，他们需要决定是否
> +应该合并补丁，分销商和其他维护人员试图决定是否应该将补丁反向移植到其他内核，
> +缺陷搜寻人员想知道补丁是否导致他们正在追查的问题，以及想知道内核如何变化的
> +用户等等。一个好的变更日志以最直接和最简洁的方式向所有这些人传达所需的信息。
>
> -为此，总结行应该描述变更的影响和动机，以及在一行约束条件下可能发生的变化。
> +在结尾，总结行应该描述变更的影响和动机，以及在一行约束条件下可能发生的变化。
> 然后，详细的描述可以详述这些主题，并提供任何需要的附加信息。如果补丁修复了
> -一个bug，请引用引入该bug的commit（如果可能，请在引用commits时同时提供commit id
> -和标题）。如果某个问题与特定的日志或编译器输出相关联，请包含该输出以帮助其他
> -人搜索同一问题的解决方案。如果更改是为了支持以后补丁中的其他更改，那么就这么
> -说。如果更改了内部API，请详细说明这些更改以及其他开发人员应该如何响应。一般
> -来说，你越能把自己放在每个阅读你的changelog的人的位置上，changelog（和内核
> +一个缺陷，请引用引入该缺陷的提交（如果可能，请在引用提交时同时提供其 id 和
> +标题）。如果某个问题与特定的日志或编译器输出相关联，请包含该输出以帮助其他
> +人搜索同一问题的解决方案。如果更改是为了支持以后补丁中的其他更改，那么应当
> +说明。如果更改了内部API，请详细说明这些更改以及其他开发人员应该如何响应。
> +一般来说，你越把自己放在每个阅读你变更日志的人的位置上，变更日志（和内核
> 作为一个整体）就越好。
>
> -不用说，变更日志应该是将变更提交到修订控制系统时使用的文本。接下来是：
> +不消说，变更日志是将变更提交到版本控制系统时使用的文本。接下来将是：
>
> - - 补丁本身，采用统一的（“-u”）补丁格式。将“-p”选项用于diff将使函数名与更改
> - 相关联，从而使结果补丁更容易被其他人读取。
> + - 补丁本身，采用统一的（“-u”）补丁格式。使用“-p”选项来diff将使函数名与
> + 更改相关联，从而使结果补丁更容易被其他人读取。
>
> -您应该避免在补丁中包括对不相关文件（例如，由构建过程生成的文件或编辑器
> -备份文件）的更改。文档目录中的文件“dontdiff”在这方面有帮助；使用“-X”选项将
> +您应该避免在补丁中包括与更改不相关文件（例如，构建过程生成的文件或编辑器
> +备份文件）。文档目录中的“dontdiff”文件在这方面有帮助；使用“-X”选项将
> 其传递给diff。
>
> -上面提到的标签用于描述各种开发人员如何与这个补丁的开发相关联。
> +上面提到的标签（tag）用于描述各种开发人员如何与这个补丁的开发相关联。
> :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
> 文档中对它们进行了详细描述；下面是一个简短的总结。每一行的格式如下：
>
> @@ -154,87 +161,87 @@ bug搜寻人员想知道补丁是否负责他们正在追查的问题，想知
>
> 常用的标签有：
>
> - - Signed-off-by: 这是一个开发人员的证明，他或她有权提交补丁以包含到内核中。
> - 这是开发来源认证协议，其全文可在
> + - Signed-off-by: 这是一个开发人员的证明，证明他或她有权提交补丁以包含到内核
> + 中。这表明同意开发者来源认证协议，其全文见
> :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
> - 中找到，如果没有适当的签字，则不能合并到主线中。
> + 如果没有合适的签字，则不能合并到主线中。
>
> - Co-developed-by: 声明补丁是由多个开发人员共同创建的；当几个人在一个补丁上
> - 工作时，它用于将属性赋予共同作者（除了 From: 所赋予的作者之外）。因为
> - Co-developed-by: 表示作者身份，所以每个共同开发人, 必须紧跟在相关合作作者
> - 的签名之后。具体内容和示例可以在以下文件中找到
> + 工作时，它用于给出共同作者（除了 From: 所给出的作者之外）。由于
> + Co-developed-by: 表示作者身份，所以每个共同开发人，必须紧跟在相关合作作者
> + 的Signed-off-by之后。具体内容和示例见以下文件
> :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
>
> - Acked-by: 表示另一个开发人员（通常是相关代码的维护人员）同意补丁适合包含
> 在内核中。
>
> - - Tested-by: 声明指定的人已经测试了补丁并发现它可以工作。
> + - Tested-by: 声明某人已经测试了补丁并确认它可以工作。
>
> - - Reviewed-by: 指定的开发人员已经审查了补丁的正确性；有关详细信息，请参阅
> + - Reviewed-by: 表示某开发人员已经审查了补丁的正确性；有关详细信息，请参阅
> :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
>
> - - Reported-by: 指定报告此补丁修复的问题的用户；此标记用于提供感谢。
> + - Reported-by: 指定报告此补丁修复的问题的用户；此标记用于表示感谢。
>
> - - Cc：指定的人收到了补丁的副本，并有机会对此发表评论。
> + - Cc：指定某人收到了补丁的副本，并有机会对此发表评论。
>
> -在补丁中添加标签时要小心：只有cc:才适合在没有指定人员明确许可的情况下添加。
> +在补丁中添加标签时要小心：只有Cc:才适合在没有指定人员明确许可的情况下添加。
>
> 发送补丁
> --------
>
> -在邮寄补丁之前，您还需要注意以下几点：
> +在寄出补丁之前，您还需要注意以下几点：
>
> - - 您确定您的邮件发送程序不会损坏补丁吗？有免费的空白更改或由邮件客户端
> - 执行的行包装的补丁不会在另一端复原，并且通常不会进行任何详细检查。如果有
> - 任何疑问，把补丁寄给你自己，让你自己相信它是完好无损的。
> + - 您确定您的邮件发送程序不会损坏补丁吗？被邮件客户端更改空白或修饰了行的补丁
> + 无法被另一端接受，并且通常不会进行任何详细检查。如果有任何疑问，先把补丁寄
> + 给你自己，让你自己确定它是完好无损的。
>
> :ref:`Documentation/translations/zh_CN/process/email-clients.rst <cn_email_clients>`
> - 提供了一些有用的提示，可以让特定的邮件客户机工作以发送补丁。
> + 提供了一些有用的提示，可以让特定的邮件客户端正常发送补丁。
>
> - - 你确定你的补丁没有愚蠢的错误吗？您应该始终通过scripts/checkpatch.pl运行
> - 补丁程序，并解决它提出的投诉。请记住，checkpatch.pl虽然是大量思考内核
> - 补丁应该是什么样子的体现，但它并不比您聪明。如果修复checkpatch.pl投诉会
> + - 你确定你的补丁没有荒唐的错误吗？您应该始终通过scripts/checkpatch.pl检查
> + 补丁程序，并解决它提出的问题。请记住，checkpatch.pl，虽然体现了对内核补丁
> + 应该是什么样的大量思考，但它并不比您聪明。如果修复checkpatch.pl给的问题会
> 使代码变得更糟，请不要这样做。
>
> 补丁应始终以纯文本形式发送。请不要将它们作为附件发送；这使得审阅者在答复中更难
> 引用补丁的部分。相反，只需将补丁直接放到您的消息中。
>
> -邮寄补丁时，重要的是将副本发送给任何可能感兴趣的人。与其他一些项目不同，内核
> -鼓励人们错误地发送过多的副本；不要假定相关人员会看到您在邮件列表中的发布。
> +寄出补丁时，重要的是将副本发送给任何可能感兴趣的人。与其他一些项目不同，内核
> +鼓励人们甚至错误地发送过多的副本；不要假定相关人员会看到您在邮件列表中的发布。
> 尤其是，副本应发送至：
>
> - - 受影响子系统的维护人员。如前所述，维护人员文件是查找这些人员的第一个地方。
> + - 受影响子系统的维护人员。如前所述，维护人员文件是查找这些人员的首选地方。
>
> - 其他在同一领域工作的开发人员，尤其是那些现在可能在那里工作的开发人员。使用
> git查看还有谁修改了您正在处理的文件，这很有帮助。
>
> - - 如果您对错误报告或功能请求做出响应，也可以抄送原始发送人。
> + - 如果您对某错误报告或功能请求做出响应，也可以抄送原始发送人。
>
> - - 将副本发送到相关邮件列表，或者，如果没有其他应用，则发送到Linux内核列表。
> + - 将副本发送到相关邮件列表，或者若无相关列表，则发送到linux-kernel列表。
>
> - - 如果您正在修复一个bug，请考虑该修复是否应进入下一个稳定更新。如果是这样，
> - stable@vger.kernel.org 应该得到补丁的副本。另外，在补丁本身的标签中添加
> - 一个“cc:stable@vger.kernel.org”；这将使稳定团队在修复进入主线时收到通知。
> + - 如果您正在修复一个缺陷，请考虑该修复是否应进入下一个稳定更新。如果是这样，
> + 补丁副本也应发到stable@vger.kernel.org 。另外，在补丁本身的标签中添加一个
> + “Cc: stable@vger.kernel.org”；这将使稳定版团队在修复进入主线时收到通知。
>
> -当为一个补丁选择接收者时，最好知道你认为谁最终会接受这个补丁并将其合并。虽然
> -可以将补丁直接发送给LinusTorvalds并让他合并，但通常情况下不会这样做。Linus
> -很忙，并且有子系统维护人员负责监视内核的特定部分。通常您会希望维护人员合并您
> -的补丁。如果没有明显的维护人员，Andrew Morton通常是最后的补丁目标。
> +当为一个补丁选择接收者时，最好清楚你认为谁最终会接受这个补丁并将其合并。虽然
> +可以将补丁直接发给Linus Torvalds并让他合并，但通常情况下不会这样做。Linus很
> +忙，并且有子系统维护人员负责监视内核的特定部分。通常您会希望维护人员合并您的
> +补丁。如果没有明显的维护人员，Andrew Morton通常是最后的补丁接收者。
>
> -补丁需要好的主题行。补丁程序行的规范格式如下：
> +补丁需要好的主题行。补丁主题行的规范格式如下：
>
> ::
>
> [PATCH nn/mm] subsys: one-line description of the patch
>
> -其中“nn”是补丁的序号，“mm”是系列中补丁的总数，“subsys”是受影响子系统的名称。
> -显然，一个单独的补丁可以省略nn/mm。
> +其中“nn”是补丁的序号，“mm”是系列中补丁的总数，“subsys”是受影响子系统的
> +名称。当然，一个单独的补丁可以省略nn/mm。
>
> -如果您有一系列重要的补丁，那么通常将介绍性描述作为零部分发送。不过，这种约定
> -并没有得到普遍遵循；如果您使用它，请记住简介中的信息不会使它进入内核变更日志。
> +如果您有一系列重要的补丁，那么通常发送一个简介作为第〇部分。不过，这个约定
> +并没有得到普遍遵循；如果您使用它，请记住简介中的信息不会进入内核变更日志。
> 因此，请确保补丁本身具有完整的变更日志信息。
>
> 一般来说，多部分补丁的第二部分和后续部分应作为对第一部分的回复发送，以便它们
> 在接收端都连接在一起。像git和coilt这样的工具有命令，可以通过适当的线程发送
> -一组补丁。但是，如果您有一个长系列，并且正在使用git，请远离–chain reply-to
> -选项，以避免创建异常深的嵌套。
> +一组补丁。但是，如果您有一长串补丁，并正使用git，请不要使用–-chain-reply-to
> +选项，以避免创建过深的嵌套。
>
^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH v3 7/9] docs/zh_CN: Improve zh_CN/process/6.Followthrough
2021-03-05 5:25 [PATCH v3 0/9] docs/zh_CN: Improve language in zh_CN/process/ Wu XiangCheng
` (5 preceding siblings ...)
2021-03-05 5:27 ` [PATCH v3 6/9] docs/zh_CN: Improve zh_CN/process/5.Posting.rst Wu XiangCheng
@ 2021-03-05 5:28 ` Wu XiangCheng
2021-03-05 5:28 ` [PATCH v3 8/9] docs/zh_CN: Improve zh_CN/process/7.AdvancedTopics Wu XiangCheng
` (2 subsequent siblings)
9 siblings, 0 replies; 12+ messages in thread
From: Wu XiangCheng @ 2021-03-05 5:28 UTC (permalink / raw)
To: alex.shi; +Cc: corbet, linux-doc
Improve language and grammar of zh_CN/process/6.Followthrough.rst
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
---
.../zh_CN/process/6.Followthrough.rst | 165 +++++++++---------
1 file changed, 86 insertions(+), 79 deletions(-)
diff --git a/Documentation/translations/zh_CN/process/6.Followthrough.rst b/Documentation/translations/zh_CN/process/6.Followthrough.rst
index f509e077e1cb..2a127e737b6a 100644
--- a/Documentation/translations/zh_CN/process/6.Followthrough.rst
+++ b/Documentation/translations/zh_CN/process/6.Followthrough.rst
@@ -1,145 +1,152 @@
.. include:: ../disclaimer-zh_CN.rst
:Original: :ref:`Documentation/process/6.Followthrough.rst <development_followthrough>`
-:Translator: Alex Shi <alex.shi@linux.alibaba.com>
+
+:Translator:
+
+ 时奎亮 Alex Shi <alex.shi@linux.alibaba.com>
+
+:校译:
+
+ 吴想成 Wu XiangCheng <bobwxc@email.cn>
.. _cn_development_followthrough:
跟进
====
-在这一点上，您已经遵循了到目前为止给出的指导方针，并且，随着您自己的工程技能
-的增加，已经发布了一系列完美的补丁。即使是经验丰富的内核开发人员也能犯的最大
-错误之一是，认为他们的工作现在已经完成了。事实上，发布补丁意味着进入流程的下
-一个阶段，可能还需要做很多工作。
+此时，您已经遵循了到目前为止给出的指导方针，并且，随着您自己的工程技能的增加，
+已经发布了一系列完美的补丁。即使是经验丰富的内核开发人员也能犯的最大错误之一
+是，认为他们的工作现在已经完成了。事实上，发布补丁意味着进入流程的下一个阶段，
+可能还需要做很多工作。
-一个补丁在第一次发布时就非常出色，没有改进的余地,这是很罕见的。内核开发流程
-认识到这一事实，因此，它非常注重对已发布代码的改进。作为代码的作者，您应该与
+一个补丁在首次发布时就非常出色、没有改进的余地，这是很罕见的。内核开发流程已
+认识到这一事实，因此它非常注重对已发布代码的改进。作为代码的作者，您应该与
内核社区合作，以确保您的代码符合内核的质量标准。如果不参与这个过程，很可能会
-阻止将补丁包含到主线中。
+无法将补丁合并到主线中。
与审阅者合作
------------
任何意义上的补丁都会导致其他开发人员在审查代码时发表大量评论。对于许多开发
-人员来说，与审查人员合作可能是内核开发过程中最令人生畏的部分。但是，如果你
+人员来说，与审阅人员合作可能是内核开发过程中最令人生畏的部分。但是如果你
记住一些事情，生活会变得容易得多：
- - 如果你已经很好地解释了你的补丁，评论人员会理解它的价值，以及为什么你会
- 费尽心思去写它。但是这个并不能阻止他们提出一个基本的问题：五年或十年后
- 用这个代码维护一个内核会是什么感觉？你可能被要求做出的许多改变——从编码风格
- 的调整到大量的重写——都来自于对Linux的理解，即从现在起十年后，Linux仍将在
- 开发中。
+ - 如果你已经很好地解释了你的补丁，审阅人员会理解它的价值，以及为什么你会
+ 费尽心思去写它。但是这个并不能阻止他们提出一个基本的问题：在五年或十年后
+ 维护含有此代码的内核会怎么样？你可能被要求做出的许多改变——从编码风格的
+ 调整到大量的重写——都来自于对Linux的理解，即从现在起十年后，Linux仍将
+ 在开发中。
- 代码审查是一项艰苦的工作，这是一项相对吃力不讨好的工作；人们记得谁编写了
- 内核代码，但对于那些审查它的人来说，几乎没有什么持久的名声。因此，评论
+ 内核代码，但对于那些审查它的人来说，几乎没有什么长久的名声。因此，审阅
人员可能会变得暴躁，尤其是当他们看到同样的错误被一遍又一遍地犯下时。如果
- 你得到了一个看起来愤怒、侮辱或完全冒犯你的评论，抵制以同样方式回应的冲动。
- 代码审查是关于代码的，而不是关于人的，代码审查人员不会亲自攻击您。
+ 你得到了一个看起来愤怒、侮辱或完全冒犯你的评论，请抑制以同样方式回应的冲动。
+ 代码审查是关于代码的，而不是关于人的，代码审阅人员不会亲自攻击您。
- - 同样，代码审查人员也不想以牺牲你雇主的利益为代价来宣传他们雇主的议程。
+ - 同样，代码审阅人员也不想以牺牲你雇主的利益为代价来宣传他们雇主的议程。
内核开发人员通常希望今后几年能在内核上工作，但他们明白他们的雇主可能会改
变。他们真的，几乎毫无例外地，致力于创造他们所能做到的最好的内核；他们并
没有试图给雇主的竞争对手造成不适。
-所有这些归根结底都是，当审阅者向您发送评论时，您需要注意他们正在进行的技术
-观察。不要让他们的表达方式或你自己的骄傲阻止这种事情的发生。当你在一个补丁
-上得到评论时，花点时间去理解评论人想说什么。如果可能的话，请修复审阅者要求
-您修复的内容。然后回复审稿人：谢谢他们，并描述你将如何回答他们的问题。
+所有这些归根结底就是，当审阅者向您发送评论时，您需要注意他们正在进行的技术
+评论。不要让他们的表达方式或你自己的骄傲阻止此事。当你在一个补丁上得到评论
+时，花点时间去理解评论人想说什么。如果可能的话，请修复审阅者要求您修复的内
+容。然后回复审阅者：谢谢他们，并描述你将如何回答他们的问题。
请注意，您不必同意审阅者建议的每个更改。如果您认为审阅者误解了您的代码，请
解释到底发生了什么。如果您对建议的更改有技术上的异议，请描述它并证明您对该
-问题的解决方案是正确的。如果你的解释有道理，审稿人会接受的。不过，如果你的
-解释不能证明是有说服力的，尤其是当其他人开始同意审稿人的观点时，请花些时间
-重新考虑一下。你很容易对自己解决问题的方法视而不见，以至于你没有意识到某个
-问题根本是错误的，或者你甚至没有解决正确的问题。
+问题的解决方案是正确的。如果你的解释有道理，审阅者会接受的。不过，如果你的
+解释证明缺乏说服力，尤其是当其他人开始同意审稿人的观点时，请花些时间重新考虑
+一下。你很容易对自己解决问题的方法视而不见，以至于你没有意识到某些东西完全
+是错误的，或者你甚至没有解决正确的问题。
-Andrew Morton建议，每一条不会导致代码更改的评论都应该导致额外的代码注释；
-这可以帮助未来的评论人员避免出现第一次出现的问题。
+Andrew Morton建议，每一个不会导致代码更改的审阅评论都应该产生一个额外的代码
+注释；这可以帮助未来的审阅人员避免第一次出现的问题。
-一个致命的错误是忽视评论，希望它们会消失。他们不会走的。如果您在没有对之前
-收到的注释做出响应的情况下重新发布代码，那么很可能会发现补丁毫无用处。
+一个致命的错误是忽视评论，希望它们会消失。它们不会走的。如果您在没有对之前
+收到的评论做出响应的情况下重新发布代码，那么很可能会发现补丁毫无用处。
说到重新发布代码：请记住，审阅者不会记住您上次发布的代码的所有细节。因此，
-提醒审查人员以前提出的问题以及您如何处理这些问题总是一个好主意；补丁变更
+提醒审阅人员以前提出的问题以及您如何处理这些问题总是一个好主意；补丁变更
日志是提供此类信息的好地方。审阅者不必搜索列表档案来熟悉上次所说的内容；
-如果您帮助他们开始运行，当他们重新访问您的代码时，他们的心情会更好。
+如果您帮助他们直接开始，当他们重新查看您的代码时，心情会更好。
如果你已经试着做正确的事情，但事情仍然没有进展呢？大多数技术上的分歧都可以
-通过讨论来解决，但有时人们只需要做出决定。如果你真的认为这个决定对你不利，
-你可以试着向更高的权力上诉。在这篇文章中，更高的权力倾向于Andrew Morton。
-Andrew在内核开发社区中受i很大的尊重；他经常为似乎被绝望地阻塞事情清障。
-尽管如此，对Andrew的呼吁不应轻而易举，也不应在所有其他替代方案都被探索之前
-使用。当然，记住，他也可能不同意你的意见。
+通过讨论来解决，但有时人们仍需要做出决定。如果你真的认为这个决定对你不利，
+你可以试着向有更高权力的人上诉。对于本文，更高权力的人是 Andrew Morton 。
+Andrew 在内核开发社区中非常受尊敬；他经常为似乎被绝望阻塞的事情清障。尽管
+如此，不应轻易就直接找 Andrew ，也不应在所有其他替代方案都被尝试之前找他。
+当然，记住，他也可能不同意你的意见。
接下来会发生什么
----------------
-如果一个补丁被认为是添加到内核中的一件好事，并且一旦大多数审查问题得到解决，
-下一步通常是进入子系统维护人员的树中。工作方式因子系统而异；每个维护人员都
-有自己的工作方式。特别是，可能有不止一棵树——一棵树，也许，专门用于计划下一
-个合并窗口的补丁，另一棵树用于长期工作。
+如果一个补丁被认为适合添加到内核中，并且大多数审查问题得到解决，下一步通常
+是进入子系统维护人员的树中。工作方式因子系统而异；每个维护人员都有自己的
+工作方式。特别是可能有不止一棵树——也许一棵树专门用于计划下一个合并窗口的
+补丁，另一棵树用于长期工作。
-对于应用于没有明显子系统树（例如内存管理修补程序）的区域的修补程序，默认树
-通常以-mm结尾。影响多个子系统的补丁也可以最终通过-mm树。
+对于应用到不属于明显子系统树（例如内存管理修补程序）的区域的修补程序，默认树
+通常上溯到-mm。影响多个子系统的补丁也可以最终进入-mm树。
包含在子系统树中可以提高补丁的可见性。现在，使用该树的其他开发人员将默认获
得补丁。子系统树通常也为Linux提供支持，使其内容对整个开发社区可见。在这一点
上，您很可能会从一组新的审阅者那里得到更多的评论；这些评论需要像上一轮那样
-得到回答。
+得到回应。
-在这一点上也会发生什么，这取决于你的补丁的性质，是与其他人正在做的工作发生
+在这时也会发生点什么，这取决于你的补丁的性质，是否与其他人正在做的工作发生
冲突。在最坏的情况下，严重的补丁冲突可能会导致一些工作被搁置，以便剩余的补丁
可以成形并合并。另一些时候，冲突解决将涉及到与其他开发人员合作，可能还会
在树之间移动一些补丁，以确保所有的应用都是干净的。这项工作可能是一件痛苦的
-事情，但要计算您的福祉：在Linux下一棵树出现之前，这些冲突通常只在合并窗口
-中出现，必须迅速解决。现在可以在合并窗口打开之前，在空闲时解决这些问题。
+事情，但也需庆幸现在的幸福：在linux-next树出现之前，这些冲突通常只在合并窗口
+中出现，必须迅速解决。现在可以在合并窗口打开之前的空闲时间解决这些问题。
有朝一日，如果一切顺利，您将登录并看到您的补丁已经合并到主线内核中。祝贺你！
-然而，一旦庆祝活动完成（并且您已经将自己添加到维护人员文件中），就值得记住
-一个重要的小事实：工作仍然没有完成。并入主线带来了自身的挑战。
+然而，一旦庆祝完了（并且您已经将自己添加到维护人员文件中），就一定要记住
+一个重要的小事实：工作仍然没有完成。并入主线也带来了它的挑战。
-首先，补丁的可见性再次提高。可能会有新一轮的开发者评论，他们以前不知道这
-个补丁。忽略它们可能很有诱惑力，因为您的代码不再存在任何被合并的问题。但是，
-要抵制这种诱惑，您仍然需要对有问题或建议的开发人员作出响应。
+首先，补丁的可见性再次提高。可能会有以前不知道这个补丁的开发者的新一轮评论。
+忽略它们可能很有诱惑力，因为您的代码不再存在任何被合并的问题。但是，要抵制
+这种诱惑，您仍然需要对有问题或建议的开发人员作出响应。
-不过，更重要的是：将代码包含在主线中会将代码交给更大的一组测试人员。即使您
-为尚未提供的硬件提供了驱动程序，您也会惊讶于有多少人会将您的代码构建到内核
-中。当然，如果有测试人员，也会有错误报告。
+不过，更重要的是：将代码包含在主线中会将代码交给更多的一些测试人员。即使您
+为尚未可用的硬件提供了驱动程序，您也会惊讶于有多少人会将您的代码构建到内核
+中。当然，如果有测试人员，也可能会有错误报告。
-最糟糕的错误报告是回归。如果你的补丁导致回归，你会发现很多不舒服的眼睛盯着
-你；回归需要尽快修复。如果您不愿意或无法修复回归（其他人都不会为您修复），
+最糟糕的错误报告是回归。如果你的补丁导致回归，你会发现多到让你不舒服的眼睛盯
+着你；回归需要尽快修复。如果您不愿意或无法修复回归（其他人都不会为您修复），
那么在稳定期内，您的补丁几乎肯定会被移除。除了否定您为使补丁进入主线所做的
-所有工作之外，如果由于未能修复回归而取消补丁，很可能会使将来的工作更难合并。
+所有工作之外，如果由于未能修复回归而取消补丁，很可能会使将来的工作更难被合并。
-在处理完任何回归之后，可能还有其他普通的bug需要处理。稳定期是修复这些错误并
-确保代码在主线内核版本中的首次发布尽可能可靠的最好机会。所以，请回答错误
+在处理完任何回归之后，可能还有其他普通缺陷需要处理。稳定期是修复这些错误并
+确保代码在主线内核版本中的首次发布尽可能可靠的最好机会。所以，请回应错误
报告，并尽可能解决问题。这就是稳定期的目的；一旦解决了旧补丁的任何问题，就
-可以开始创建酷的新补丁。
+可以开始尽情创建新补丁。
-别忘了，还有其他里程碑也可能会创建bug报告：下一个主线稳定版本，当著名的发行
-商选择包含补丁的内核版本时，等等。继续响应这些报告是您工作的基本骄傲。但是，
-如果这不是足够的动机，那么也值得考虑的是，开发社区会记住那些在合并后对代码
-失去兴趣的开发人员。下一次你发布补丁时，他们会以你以后不会在身边维护它为假
-设来评估它。
+别忘了，还有其他节点也可能会创建缺陷报告：下一个主线稳定版本，当著名的发行
+商选择包含您补丁的内核版本时等等。继续响应这些报告是您工作的基本素养。但是
+如果这不能提供足够的动机，那么也需要考虑：开发社区会记住那些在合并后对代码
+失去兴趣的开发人员。下一次你发布补丁时，他们会以你以后不会持续维护它为前提
+来评估它。
其他可能发生的事情
------------------
-有一天，你可以打开你的邮件客户端，看到有人给你寄了一个代码补丁。毕竟，这是
+某天，当你打开你的邮件客户端时，看到有人给你寄了一个代码补丁。毕竟，这是
让您的代码公开存在的好处之一。如果您同意这个补丁，您可以将它转发给子系统
-维护人员（确保包含一个正确的From:行，这样属性是正确的，并添加一个您自己
-的签准），或者回复一个Acked-by，让原始发送者向上发送它。
+维护人员（确保包含一个正确的From:行，这样属性是正确的，并添加一个您自己的
+signoff ），或者回复一个 Acked-by: 让原始发送者向上发送它。
-如果您不同意补丁，请发送一个礼貌的回复，解释原因。如果可能的话，告诉作者需要
-做哪些更改才能让您接受补丁。对于代码的编写者和维护者所反对的合并补丁，存在着
-一定的阻力，但仅此而已。如果你被认为不必要的阻碍了好的工作，那么这些补丁最
-终会经过你身边并进入主线。在Linux内核中，没有人对任何代码拥有绝对的否决权。
-除了Linus。
+如果您不同意补丁，请礼貌地回复，解释原因。如果可能的话，告诉作者需要做哪些
+更改才能让您接受补丁。合并代码的编写者和维护者所反对的补丁的确存在着一定的
+阻力，但仅此而已。如果你被认为不必要的阻碍了好的工作，那么这些补丁最终会
+绕过你并进入主线。在Linux内核中，没有人对任何代码拥有绝对的否决权。可能除
+了Linus。
在非常罕见的情况下，您可能会看到完全不同的东西：另一个开发人员发布了针对您
-的问题的不同解决方案。在这一点上，两个补丁中的一个可能不会合并，“我的在这里
-是第一个”不被认为是一个令人信服的技术论据。如果有人的补丁取代了你的补丁而进
-入了主线，那么只有一种方法可以回应你：高兴你的问题得到解决，继续你的工作。
-以这种方式把一个人的工作推到一边可能会伤害和气馁，但是在他们忘记了谁的补丁
-真正被合并很久之后，社区会记住你的反应。
+的问题的不同解决方案。在这时，两个补丁之一可能不会被合并，“我的补丁首先
+发布”不被认为是一个令人信服的技术论据。如果有别人的补丁取代了你的补丁而进
+入了主线，那么只有一种方法可以回应你：很高兴你的问题解决了，请继续工作吧。
+以这种方式把某人的工作推到一边可能导致伤心和气馁，但是社区会记住你的反应，
+即使很久以后他们已经忘记了谁的补丁真正被合并。
--
2.20.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v3 8/9] docs/zh_CN: Improve zh_CN/process/7.AdvancedTopics
2021-03-05 5:25 [PATCH v3 0/9] docs/zh_CN: Improve language in zh_CN/process/ Wu XiangCheng
` (6 preceding siblings ...)
2021-03-05 5:28 ` [PATCH v3 7/9] docs/zh_CN: Improve zh_CN/process/6.Followthrough Wu XiangCheng
@ 2021-03-05 5:28 ` Wu XiangCheng
2021-03-05 5:28 ` [PATCH v3 9/9] docs/zh_CN: Improve zh_CN/process/8.Conclusion.rst Wu XiangCheng
2021-03-08 23:02 ` [PATCH v3 0/9] docs/zh_CN: Improve language in zh_CN/process/ Jonathan Corbet
9 siblings, 0 replies; 12+ messages in thread
From: Wu XiangCheng @ 2021-03-05 5:28 UTC (permalink / raw)
To: alex.shi; +Cc: corbet, linux-doc
Improve language and grammar of zh_CN/process/7.AdvancedTopics.rst
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
---
.../zh_CN/process/7.AdvancedTopics.rst | 141 ++++++++++--------
1 file changed, 75 insertions(+), 66 deletions(-)
diff --git a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst
index 2f0ef750746f..6d0dadae13b1 100644
--- a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst
+++ b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst
@@ -1,7 +1,14 @@
.. include:: ../disclaimer-zh_CN.rst
:Original: :ref:`Documentation/process/7.AdvancedTopics.rst <development_advancedtopics>`
-:Translator: Alex Shi <alex.shi@linux.alibaba.com>
+
+:Translator:
+
+ 时奎亮 Alex Shi <alex.shi@linux.alibaba.com>
+
+:校译:
+
+ 吴想成 Wu XiangCheng <bobwxc@email.cn>
.. _cn_development_advancedtopics:
@@ -15,110 +22,112 @@
---------------
内核使用分布式版本控制始于2002年初，当时Linus首次开始使用专有的Bitkeeper应用
-程序。虽然bitkeeper存在争议，但它所体现的软件版本管理方法却肯定不是。分布式
-版本控制可以立即加速内核开发项目。在当前的时代，有几种免费的比特保持器替代品。
-无论好坏，内核项目都将Git作为其选择的工具。
+程序。虽然BitKeeper存在争议，但它所体现的软件版本管理方法却肯定不是。分布式
+版本控制可以立即加速内核开发项目。现在有好几种免费的BitKeeper替代品。
+但无论好坏，内核项目都已经选择了Git作为其工具。
-使用Git管理补丁可以使开发人员的生活更加轻松，尤其是随着补丁数量的增加。Git
-也有其粗糙的边缘和一定的危险，它是一个年轻和强大的工具，仍然在其开发人员完善
+使用Git管理补丁可以使开发人员的生活更加轻松，尤其是随着补丁数量的增长。Git也
+有其粗糙的边角和一定的危险性，它是一个年轻和强大的工具，仍然在其开发人员完善
中。本文档不会试图教会读者如何使用git；这会是个巨长的文档。相反，这里的重点
-将是Git如何特别适合内核开发过程。想要加快Git的开发人员可以在以下网站上找到
-更多信息：
+将是Git如何特别适合内核开发过程。想要加快用Git速度的开发人员可以在以下网站上
+找到更多信息：
https://git-scm.com/
https://www.kernel.org/pub/software/scm/git/docs/user-manual.html
-在尝试使用它使补丁可供其他人使用之前，第一要务是阅读上述站点，对Git的工作
-方式有一个扎实的了解。使用Git的开发人员应该能够获得主线存储库的副本，探索
-修订历史，提交对树的更改，使用分支等。了解Git用于重写历史的工具（如Rebase）
-也很有用。Git有自己的术语和概念；Git的新用户应该了解refs、远程分支、索引、
-快进合并、推拉、分离头等。一开始可能有点吓人，但这些概念不难通过一点学习来
+同时网上也能找到各种各样的教程。
+
+在尝试使用它生成补丁供他人使用之前，第一要务是阅读上述网页，对Git的工作方式
+有一个扎实的了解。使用Git的开发人员应能进行拉取主线存储库的副本，查询修订
+历史，提交对树的更改，使用分支等操作。了解Git用于重写历史的工具（如rebase）
+也很有用。Git有自己的术语和概念；Git的新用户应该了解引用、远程分支、索引、
+快进合并、推拉、游离头等。一开始可能有点吓人，但这些概念不难通过一点学习来
理解。
使用git生成通过电子邮件提交的补丁是提高速度的一个很好的练习。
-当您准备好开始安装Git树供其他人查看时，您当然需要一个可以从中提取的服务器。
-如果您有一个可以访问Internet的系统，那么使用git守护进程设置这样的服务器相
-对简单。否则，免费的公共托管网站（例如github）开始出现在网络上。成熟的开发
-人员可以在kernel.org上获得一个帐户，但这些帐户并不容易找到；有关更多信息，
-请参阅 https://kernel.org/faq/
+当您准备好开始建立Git树供其他人查看时，无疑需要一个可以从中拉取的服务器。
+如果您有一个可以访问因特网的系统，那么使用git-daemon设置这样的服务器相对
+简单。同时，免费的公共托管网站（例如github）也开始出现在网络上。成熟的开发
+人员可以在kernel.org上获得一个帐户，但这些帐户并不容易得到；更多有关信息，
+请参阅 https://kernel.org/faq/ 。
正常的Git工作流程涉及到许多分支的使用。每一条开发线都可以分为单独的“主题
-分支”，并独立维护。Git的分支机构很便宜，没有理由不免费使用它们。而且，在
-任何情况下，您都不应该在任何您打算让其他人从中受益的分支中进行开发。应该
-小心地创建公开可用的分支；当它们处于完整的形式并准备好运行时(而不是之前），
-合并开发分支的补丁。
+分支”，并独立维护。Git的分支很容易使用，没有理由不使用它们。而且，在任何
+情况下，您都不应该在任何您打算让其他人从中拉取的分支中进行开发。应该小心地
+创建公开可用的分支；当开发分支处于完整状态并已准备好时(而不是之前）才合并
+开发分支的补丁。
Git提供了一些强大的工具，可以让您重写开发历史。一个不方便的补丁（比如说，
一个打破二分法的补丁，或者有其他一些明显的缺陷）可以在适当的位置修复，或者
-完全从历史中消失。一个补丁系列可以被重写，就好像它是在今天的主线之上写的
-一样，即使你已经花了几个月的时间在写它。可以透明地将更改从一个分支转移到另
-一个分支。等等。明智地使用git修改历史的能力可以帮助创建问题更少的干净补丁集。
+完全从历史中消失。一个补丁系列可以被重写，就好像它是在今天的主线上写的一样，
+即使你已经花了几个月的时间在写它。可以透明地将更改从一个分支转移到另一个
+分支。等等。明智地使用git修改历史的能力可以帮助创建问题更少的干净补丁集。
-然而，过度使用这种能力可能会导致其他问题，而不仅仅是对创建完美项目历史的
-简单痴迷。重写历史将重写该历史中包含的更改，将经过测试（希望）的内核树变
-为未经测试的内核树。但是，除此之外，如果开发人员没有对项目历史的共享视图，
-他们就无法轻松地协作；如果您重写了其他开发人员拉入他们存储库的历史，您将
-使这些开发人员的生活更加困难。因此，这里有一个简单的经验法则：被导出到其他
-人的历史在此后通常被认为是不可变的。
+然而，过度使用这种功能可能会导致其他问题，而不仅仅是对创建完美项目历史的
+简单痴迷。重写历史将重写该历史中包含的更改，将经过测试（希望如此）的内核树
+变为未经测试的内核树。除此之外，如果开发人员没有共享项目历史，他们就无法
+轻松地协作；如果您重写了其他开发人员拉入他们存储库的历史，您将使这些开发
+人员的生活更加困难。因此，这里有一个简单的经验法则：被导出到其他地方的历史
+在此后通常被认为是不可变的。
因此，一旦将一组更改推送到公开可用的服务器上，就不应该重写这些更改。如果您
-尝试强制进行不会导致快进合并（即不共享同一历史记录的更改）的更改，Git将尝
-试强制执行此规则。可以重写此检查，有时可能需要重写导出的树。在树之间移动变
-更集以避免Linux-next中的冲突就是一个例子。但这种行为应该是罕见的。这就是为
-什么开发应该在私有分支中进行（必要时可以重写）并且只有在公共分支处于合理的
-高级状态时才转移到公共分支中的原因之一。
+尝试强制进行无法快进合并的更改（即不共享同一历史记录的更改），Git将尝试强制
+执行此规则。这可能覆盖检查，有时甚至需要重写导出的树。在树之间移动变更集以
+避免linux-next中的冲突就是一个例子。但这种行为应该是罕见的。这就是为什么
+开发应该在私有分支中进行（必要时可以重写）并且只有在公共分支处于合理的较新
+状态时才转移到公共分支中的原因之一。
当主线（或其他一组变更所基于的树）前进时，很容易与该树合并以保持领先地位。
对于一个私有的分支，rebasing 可能是一个很容易跟上另一棵树的方法，但是一旦
-一棵树被导出到全世界，rebasing就不是一个选项。一旦发生这种情况，就必须进行
-完全合并（merge）。合并有时是很有意义的，但是过于频繁的合并会不必要地扰乱
-历史。在这种情况下，建议的技术是不经常合并，通常只在特定的发布点（如主线-rc
-发布）合并。如果您对特定的更改感到紧张，则可以始终在私有分支中执行测试合并。
-在这种情况下，git rerere 工具很有用；它记住合并冲突是如何解决的，这样您就
-不必重复相同的工作。
+一棵树被导出到外界，rebasing就不可取了。一旦发生这种情况，就必须进行完全
+合并（merge）。合并有时是很有意义的，但是过于频繁的合并会不必要地扰乱历史。
+在这种情况下建议的做法是不要频繁合并，通常只在特定的发布点（如主线-rc发布）
+合并。如果您对特定的更改感到紧张，则可以始终在私有分支中执行测试合并。在
+这种情况下，git“rerere”工具很有用；它能记住合并冲突是如何解决的，这样您
+就不必重复相同的工作。
关于Git这样的工具的一个最大的反复抱怨是：补丁从一个存储库到另一个存储库的
大量移动使得很容易陷入错误建议的变更中，这些变更避开审查雷达进入主线。当内
-核开发人员看到这种情况发生时，他们往往会感到不高兴；在Git树上放置未查看或
-主题外的补丁可能会影响您将来获取树的能力。引用Linus:
+核开发人员看到这种情况发生时，他们往往会感到不高兴；在Git树上放置未审阅或
+主题外的补丁可能会影响您将来让树被拉取的能力。引用Linus的话:
::
- 你可以给我发补丁，但要我从你哪里取一个Git补丁，我需要知道你知道
- 你在做什么，我需要能够相信事情而不去检查每个个人改变。
+ 你可以给我发补丁，但当我从你那里拉取一个Git补丁时，我需要知道你清楚
+ 自己在做什么，我需要能够相信事情而 *无需* 手动检查每个单独的更改。
（http://lwn.net/articles/224135/）。
为了避免这种情况，请确保给定分支中的所有补丁都与相关主题紧密相关；“驱动程序
修复”分支不应更改核心内存管理代码。而且，最重要的是，不要使用Git树来绕过
-审查过程。不时的将树的摘要发布到相关的列表中，当时间合适时，请求
-Linux-next 中包含该树。
+审查过程。不时的将树的摘要发布到相关的列表中，在合适时候请求linux-next中
+包含该树。
-如果其他人开始发送补丁以包含到您的树中，不要忘记查看它们。还要确保您维护正确
-的作者信息； ``git am`` 工具在这方面做得最好，但是如果它通过第三方转发给您，
-您可能需要在补丁中添加“From：”行。
+如果其他人开始发送补丁以包含到您的树中，不要忘记审阅它们。还要确保您维护正确
+的作者信息； git “am”工具在这方面做得最好，但是如果补丁通过第三方转发给您，
+您可能需要在补丁中添加“From:”行。
-请求pull操作时，请务必提供所有相关信息：树的位置、要拉的分支以及拉操作将导致
-的更改。在这方面，git request pull 命令非常有用；它将按照其他开发人员的预期
-格式化请求，并检查以确保您记住了将这些更改推送到公共服务器。
+请求拉取时，请务必提供所有相关信息：树的位置、要拉取的分支以及拉取将导致的
+更改。在这方面 git request-pull 命令非常有用；它将按照其他开发人员所期望的
+格式化请求，并检查以确保您已记得将这些更改推送到公共服务器。
-审查补丁
+审阅补丁
--------
-一些读者当然会反对将本节与“高级主题”放在一起，因为即使是刚开始的内核开发人员
-也应该检查补丁。当然，学习如何在内核环境中编程没有比查看其他人发布的代码更好
-的方法了。此外，审阅者永远供不应求；通过查看代码，您可以对整个流程做出重大贡献。
+一些读者显然会反对将本节与“高级主题”放在一起，因为即使是刚开始的内核开发人员
+也应该审阅补丁。当然，没有比查看其他人发布的代码更好的方法来学习如何在内核环境
+中编程了。此外，审阅者永远供不应求；通过审阅代码，您可以对整个流程做出重大贡献。
-审查代码可能是一个令人生畏的前景，特别是对于一个新的内核开发人员来说，他们
+审查代码可能是一副令人生畏的图景，特别是对一个新的内核开发人员来说，他们
可能会对公开询问代码感到紧张，而这些代码是由那些有更多经验的人发布的。不过，
-即使是最有经验的开发人员编写的代码也可以得到改进。也许对评审员（所有评审员）
-最好的建议是：把评审评论当成问题而不是批评。询问“在这条路径中如何释放锁？”
+即使是最有经验的开发人员编写的代码也可以得到改进。也许对（所有）审阅者最好
+的建议是：把审阅评论当成问题而不是批评。询问“在这条路径中如何释放锁？”
总是比说“这里的锁是错误的”更好。
-不同的开发人员将从不同的角度审查代码。一些主要关注的是编码样式以及代码行是
-否有尾随空格。其他人将主要关注补丁作为一个整体实现的变更是否对内核有好处。
-然而，其他人会检查是否存在锁定问题、堆栈使用过度、可能的安全问题、在其他
-地方发现的代码重复、足够的文档、对性能的不利影响、用户空间ABI更改等。所有
-类型的检查，如果它们导致更好的代码进入内核，都是受欢迎和值得的。
+不同的开发人员将从不同的角度审查代码。部分人会主要关注代码风格以及代码行是
+否有尾随空格。其他人会主要关注补丁作为一个整体实现的变更是否对内核有好处。
+同时也有人会检查是否存在锁问题、堆栈使用过度、可能的安全问题、在其他地方
+发现的代码重复、足够的文档、对性能的不利影响、用户空间ABI更改等。所有类型
+的检查，只要它们能引导更好的代码进入内核，都是受欢迎和值得的。
--
2.20.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v3 9/9] docs/zh_CN: Improve zh_CN/process/8.Conclusion.rst
2021-03-05 5:25 [PATCH v3 0/9] docs/zh_CN: Improve language in zh_CN/process/ Wu XiangCheng
` (7 preceding siblings ...)
2021-03-05 5:28 ` [PATCH v3 8/9] docs/zh_CN: Improve zh_CN/process/7.AdvancedTopics Wu XiangCheng
@ 2021-03-05 5:28 ` Wu XiangCheng
2021-03-08 23:02 ` [PATCH v3 0/9] docs/zh_CN: Improve language in zh_CN/process/ Jonathan Corbet
9 siblings, 0 replies; 12+ messages in thread
From: Wu XiangCheng @ 2021-03-05 5:28 UTC (permalink / raw)
To: alex.shi; +Cc: corbet, linux-doc
Improve language and grammar of zh_CN/process/8.Conclusion.rst
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
---
.../zh_CN/process/8.Conclusion.rst | 60 ++++++++++---------
1 file changed, 33 insertions(+), 27 deletions(-)
diff --git a/Documentation/translations/zh_CN/process/8.Conclusion.rst b/Documentation/translations/zh_CN/process/8.Conclusion.rst
index 90cec3de6106..71c3e30efc6f 100644
--- a/Documentation/translations/zh_CN/process/8.Conclusion.rst
+++ b/Documentation/translations/zh_CN/process/8.Conclusion.rst
@@ -1,7 +1,13 @@
.. include:: ../disclaimer-zh_CN.rst
:Original: :ref:`Documentation/process/8.Conclusion.rst <development_conclusion>`
-:Translator: Alex Shi <alex.shi@linux.alibaba.com>
+:Translator:
+
+ 时奎亮 Alex Shi <alex.shi@linux.alibaba.com>
+
+:校译:
+
+ 吴想成 Wu XiangCheng <bobwxc@email.cn>
.. _cn_development_conclusion:
@@ -9,56 +15,56 @@
========
关于Linux内核开发和相关主题的信息来源很多。首先是在内核源代码分发中找到的
-文档目录。顶级 :ref:`Documentation/translations/zh_CN/process/howto.rst <cn_process_howto>`
-文件是一个重要的起点
+文档目录。顶级
+:ref:`Documentation/translations/zh_CN/process/howto.rst <cn_process_howto>`
+文件是一个重要的起点；
:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
-和 :ref:`process/submitting-drivers.rst <submittingdrivers>`
+和 :ref:`Documentation/transaltions/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>`
也是所有内核开发人员都应该阅读的内容。许多内部内核API都是使用kerneldoc机制
-记录的；“make htmldocs”或“make pdfdocs”可用于以HTML或PDF格式生成这些文档（
-尽管某些发行版提供的tex版本会遇到内部限制，无法正确处理文档）。
+记录的；“make htmldocs”或“make pdfdocs”可用于以HTML或PDF格式生成这些文档
+（尽管某些发行版提供的tex版本会遇到内部限制，无法正确处理文档）。
-不同的网站在各个细节层次上讨论内核开发。您的作者想谦虚地建议用 https://lwn.net/
-作为来源；有关许多特定内核主题的信息可以通过以下网址的lwn内核索引找到：
+不同的网站在各个细节层次上讨论内核开发。本文作者想谦虚地建议用 https://lwn.net/
+作为来源；有关许多特定内核主题的信息可以通过以下网址的 LWN 内核索引找到：
- http://lwn.net/kernel/index/
+ http://lwn.net/kernel/index/
除此之外，内核开发人员的一个宝贵资源是：
- https://kernelnewbies.org/
+ https://kernelnewbies.org/
-当然，我们不应该忘记 https://kernel.org/ 这是内核发布信息的最终位置。
+当然，也不应该忘记 https://kernel.org/ ，这是内核发布信息的最终位置。
关于内核开发有很多书：
- Linux设备驱动程序，第三版（Jonathan Corbet、Alessandro Rubini和Greg Kroah Hartman）。
- 在线：http://lwn.net/kernel/ldd3/
+ 《Linux设备驱动程序》第三版（Jonathan Corbet、Alessandro Rubini和Greg Kroah Hartman）
+ 线上版本在 http://lwn.net/kernel/ldd3/
- Linux内核开发（Robert Love）。
+ 《Linux内核设计与实现》（Robert Love）
- 了解Linux内核（Daniel Bovet和Marco Cesati）。
+ 《深入理解Linux内核》(Daniel Bovet和Marco Cesati）
-然而，所有这些书都有一个共同的缺点：当它们上架时，它们往往有些过时，而且它们
-已经上架一段时间了。不过，在那里还可以找到相当多的好信息。
+然而，所有这些书都有一个共同的缺点：它们上架时就往往有些过时，而且已经上架
+一段时间了。不过，在那里还是可以找到相当多的好信息。
有关git的文档，请访问：
- https://www.kernel.org/pub/software/scm/git/docs/
+ https://www.kernel.org/pub/software/scm/git/docs/
- https://www.kernel.org/pub/software/scm/git/docs/user-manual.html
+ https://www.kernel.org/pub/software/scm/git/docs/user-manual.html
结论
====
-祝贺所有通过这篇冗长的文件的人。希望它能够帮助您理解Linux内核是如何开发的，
+祝贺所有通过这篇冗长的文档的人。希望它能够帮助您理解Linux内核是如何开发的，
以及您如何参与这个过程。
-最后，重要的是参与。任何开源软件项目都不超过其贡献者投入其中的总和。Linux内核
-的发展速度和以前一样快，因为它得到了大量开发人员的帮助，他们都在努力使它变得
-更好。内核是一个主要的例子，说明当成千上万的人为了一个共同的目标一起工作时，
-可以做些什么。
+最后，重要的是参与。任何开源软件项目都不会超过其贡献者投入其中的总和。Linux
+内核的发展速度和以前一样快，因为它得到了大量开发人员的帮助，他们都在努力使它
+变得更好。内核是一个最成功的例子，说明了当成千上万的人为了一个共同的目标一起
+工作时，可以做出什么。
-不过，内核总是可以从更大的开发人员基础中获益。总有更多的工作要做。但是，同样
+不过，内核总是可以从更大的开发人员基础中获益。总有更多的工作要做。但是同样
重要的是，Linux生态系统中的大多数其他参与者可以通过为内核做出贡献而受益。使
代码进入主线是提高代码质量、降低维护和分发成本、提高对内核开发方向的影响程度
-等的关键。这是一种人人都赢的局面。踢开你的编辑，来加入我们吧，你会非常受
-欢迎的。
+等的关键。这是一种共赢的局面。启动你的编辑器，来加入我们吧；你会非常受欢迎的。
--
2.20.1
^ permalink raw reply related [flat|nested] 12+ messages in thread* Re: [PATCH v3 0/9] docs/zh_CN: Improve language in zh_CN/process/
2021-03-05 5:25 [PATCH v3 0/9] docs/zh_CN: Improve language in zh_CN/process/ Wu XiangCheng
` (8 preceding siblings ...)
2021-03-05 5:28 ` [PATCH v3 9/9] docs/zh_CN: Improve zh_CN/process/8.Conclusion.rst Wu XiangCheng
@ 2021-03-08 23:02 ` Jonathan Corbet
9 siblings, 0 replies; 12+ messages in thread
From: Jonathan Corbet @ 2021-03-08 23:02 UTC (permalink / raw)
To: Wu XiangCheng, Alex Shi; +Cc: linux-doc
Wu XiangCheng <bobwxc@email.cn> writes:
> Hi all,
>
> This set of patches aims to polish context, improve on fluency, idiomatic
> and grammar in some files in zh_CN/process/, and synchronize them with
> original files. Some structure modifications need to rewrite the whole
> sentences, so here are a lot of changes.
OK, I have applied this set, thanks.
jon
^ permalink raw reply [flat|nested] 12+ messages in thread