diff options
Diffstat (limited to 'Documentation/translations/zh_CN/process')
24 files changed, 3095 insertions, 1682 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源代码 +的法律问题，没有什么可以代替咨询了解这一领域的律师。依赖从技术邮件列表中获得 +的答案是一件冒险的事情。 diff --git a/Documentation/translations/zh_CN/process/2.Process.rst b/Documentation/translations/zh_CN/process/2.Process.rst index ceb733bb0294..e68c9de0f7f8 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版本是一个信号，表示合并新特性的时间已经过去，稳定下一 -个内核的时间已经开始。 +合并窗口持续大约两周。在这段时间结束时，Linus Torvalds将声明窗口已关闭，并 +释放第一个“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。但是，在进入 +只有一个人可以将补丁合并到主线内核存储库中：Linus Torvalds。但是，在进入 2.6.38内核的9500多个补丁中，只有112个（大约1.3%）是由Linus自己直接选择的。 -内核项目已经发展到一个规模，没有一个开发人员可以在没有支持的情况下检查和 -选择每个补丁。内核开发人员处理这种增长的方式是通过使用围绕信任链构建的 -助理系统。 +内核项目已经发展到一个没有一个开发人员可以在没有支持的情况下检查和选择每个 +补丁的规模。内核开发人员处理这种增长的方式是使用围绕信任链构建的助理系统。 -内核代码库在逻辑上被分解为一组子系统：网络、特定的体系结构支持、内存管理、 -视频设备等。大多数子系统都有一个指定的维护人员，开发人员对该子系统中的代码 -负有全部责任。这些子系统维护者（松散地）是他们所管理的内核部分的守护者； -他们（通常）会接受一个补丁以包含到主线内核中。 +内核代码库在逻辑上被分解为一组子系统：网络、特定体系结构支持、内存管理、视 +频设备等。大多数子系统都有一个指定的维护人员，其总体负责该子系统中的代码。 +这些子系统维护者（松散地）是他们所管理的内核部分的“守门员”；他们（通常） +会接受一个补丁以包含到主线内核中。 -子系统维护人员每个人都使用git源代码管理工具管理自己版本的内核源代码树。Git -等工具（以及Quilt或Mercurial等相关工具）允许维护人员跟踪补丁列表，包括作者 +子系统维护人员每个人都管理着自己版本的内核源代码树，通常（并非总是）使用Git。 +Git等工具（以及Quilt或Mercurial等相关工具）允许维护人员跟踪补丁列表，包括作者 信息和其他元数据。在任何给定的时间，维护人员都可以确定他或她的存储库中的哪 些补丁在主线中找不到。 -当合并窗口打开时，顶级维护人员将要求Linus从其存储库中“拉出”他们为合并选择 +当合并窗口打开时，顶级维护人员将要求Linus从存储库中“拉出”他们为合并选择 的补丁。如果Linus同意，补丁流将流向他的存储库，成为主线内核的一部分。 -Linus对拉操作中接收到的特定补丁的关注程度各不相同。很明显，有时他看起来很 -关注。但是，作为一般规则，Linus相信子系统维护人员不会向上游发送坏补丁。 +Linus对拉取中接收到的特定补丁的关注程度各不相同。很明显，有时他看起来很 +关注。但是一般来说，Linus相信子系统维护人员不会向上游发送坏补丁。 子系统维护人员反过来也可以从其他维护人员那里获取补丁。例如，网络树是由首先 在专用于网络设备驱动程序、无线网络等的树中积累的补丁构建的。此存储链可以 @@ -195,32 +201,32 @@ 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）目录中找到： - http://www.ozlabs.org/~akpm/mmotm/ + https://www.ozlabs.org/~akpm/mmotm/ -然而，使用mmotm树可能是一种令人沮丧的体验；它甚至可能无法编译。 +然而，使用MMOTM树可能会十分令人头疼；它甚至可能无法编译。 下一个周期补丁合并的主要树是linux-next，由Stephen Rothwell 维护。根据设计 linux-next 是下一个合并窗口关闭后主线的快照。linux-next树在Linux-kernel 和 Linux-next 邮件列表中发布，可从以下位置下载： - http://www.kernel.org/pub/linux/kernel/next/ + https://www.kernel.org/pub/linux/kernel/next/ Linux-next 已经成为内核开发过程中不可或缺的一部分；在一个给定的合并窗口中合并 的所有补丁都应该在合并窗口打开之前的一段时间内找到进入Linux-next 的方法。 @@ -228,51 +234,50 @@ 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主页位于： - http://git-scm.com/ + https://git-scm.com/ -那个页面有指向文档和教程的指针。 +此页面包含了文档和教程的链接。 -在不使用git的内核开发人员中，最流行的选择几乎肯定是mercurial： +在不使用git的内核开发人员中，最流行的选择几乎肯定是Mercurial： http://www.seleric.com/mercurial/ Mercurial与Git共享许多特性，但它提供了一个界面，许多人觉得它更易于使用。 -另一个值得了解的工具是quilt: +另一个值得了解的工具是Quilt: - http://savannah.nongnu.org/projects/quilt + https://savannah.nongnu.org/projects/quilt 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/) +(http://lwn.net/Articles/283982/) -在没有明显问题需要解决的情况下，建议开发人员查看当前的回归和开放式错误列表. -解决需要修复的问题没有任何缺点；通过解决这些问题，开发人员将获得处理过程的 -经验，同时与开发社区的其他人建立尊重。 +在没有明显问题需要解决的情况下，通常建议开发人员查看当前的回归和开放缺陷 +列表。从来都不缺少需要解决的问题；通过解决这些问题，开发人员将从该过程获得 +经验，同时与开发社区的其他成员建立相互尊重。 diff --git a/Documentation/translations/zh_CN/process/3.Early-stage.rst b/Documentation/translations/zh_CN/process/3.Early-stage.rst index b8676aec6005..2caba4753b75 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/） +（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/ 这种审查通常足以避免以后出现严重问题，而无需公开披露项目。 diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst index b82b1dde3122..7cac9424f5d5 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/） + 所以我们不会通过引入新问题来修复错误。这种方式是靠不住的，没人知道 + 是否真的有进展。是前进两步、后退一步，还是前进一步、后退两步？ + +（http://lwn.net/Articles/243460/） -一种特别不受欢迎的回归类型是用户空间ABI的任何变化。一旦接口被导出到用户空间， +特别不受欢迎的一种回归类型是用户空间ABI的任何变化。一旦接口被导出到用户空间， 就必须无限期地支持它。这一事实使得用户空间接口的创建特别具有挑战性：因为它们 -不能以不兼容的方式进行更改，所以必须第一次正确地进行更改。因此，用户空间界面 -总是需要大量的思考、清晰的文档和广泛的审查。 +不能以不兼容的方式进行更改，所以必须一次就对。因此，用户空间接口总是需要大量 +的思考、清晰的文档和广泛的审查。 代码检查工具 @@ -157,60 +162,58 @@ Linus对这个问题给出了最佳答案: 至少目前，编写无错误代码仍然是我们中很少人能达到的理想状态。不过，我们希望做 的是，在代码进入主线内核之前，尽可能多地捕获并修复这些错误。为此，内核开发人 -员已经组装了一系列令人印象深刻的工具，可以自动捕获各种各样的模糊问题。计算机 +员已经提供了一系列令人印象深刻的工具，可以自动捕获各种各样的隐藏问题。计算机 发现的任何问题都是一个以后不会困扰用户的问题，因此，只要有可能，就应该使用 自动化工具。 -第一步只是注意编译器产生的警告。当代版本的GCC可以检测（并警告）大量潜在错误。 -通常，这些警告都指向真正的问题。提交以供审阅的代码通常不会产生任何编译器警告。 -在消除警告时，注意了解真正的原因，并尽量避免“修复”，使警告消失而不解决其原因。 +第一步是注意编译器产生的警告。当前版本的GCC可以检测（并警告）大量潜在错误。 +通常，这些警告都指向真正的问题。提交以供审阅的代码一般不会产生任何编译器警告。 +在消除警告时，注意了解真正的原因，并尽量避免仅“修复”使警告消失而不解决其原因。 -请注意，并非所有编译器警告都默认启用。使用“make EXTRA_CFLAGS=-W”构建内核以 +请注意，并非所有编译器警告都默认启用。使用“make KCFLAGS=-W”构建内核以 获得完整集合。 内核提供了几个配置选项，可以打开调试功能；大多数配置选项位于“kernel hacking” 子菜单中。对于任何用于开发或测试目的的内核，都应该启用其中几个选项。特别是， 您应该打开： - - 启用 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,10 +224,10 @@ scripts/coccinelle目录下已经打包了相当多的内核“语义补丁” 其他类型的可移植性错误最好通过为其他体系结构编译代码来发现。如果没有S/390系统 -或Blackfin开发板，您仍然可以执行编译步骤。可以在以下位置找到一组用于x86系统的 -大型交叉编译器： +或Blackfin开发板，您仍然可以执行编译步骤。可以在以下位置找到一大堆用于x86系统的 +交叉编译器： - http://www.kernel.org/pub/tools/crosstool/ + 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更改时，应尽可能确保编译器捕获未更新的代码。这将帮助您确保找 diff --git a/Documentation/translations/zh_CN/process/5.Posting.rst b/Documentation/translations/zh_CN/process/5.Posting.rst index 41aba21ff050..6a469e1c7deb 100644 --- a/Documentation/translations/zh_CN/process/5.Posting.rst +++ b/Documentation/translations/zh_CN/process/5.Posting.rst @@ -1,150 +1,156 @@ .. 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/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 +160,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 +选项，以避免创建过深的嵌套。 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。 在非常罕见的情况下，您可能会看到完全不同的东西：另一个开发人员发布了针对您 -的问题的不同解决方案。在这一点上，两个补丁中的一个可能不会合并，“我的在这里 -是第一个”不被认为是一个令人信服的技术论据。如果有人的补丁取代了你的补丁而进 -入了主线，那么只有一种方法可以回应你：高兴你的问题得到解决，继续你的工作。 -以这种方式把一个人的工作推到一边可能会伤害和气馁，但是在他们忘记了谁的补丁 -真正被合并很久之后，社区会记住你的反应。 +的问题的不同解决方案。在这时，两个补丁之一可能不会被合并，“我的补丁首先 +发布”不被认为是一个令人信服的技术论据。如果有别人的补丁取代了你的补丁而进 +入了主线，那么只有一种方法可以回应你：很高兴你的问题解决了，请继续工作吧。 +以这种方式把某人的工作推到一边可能导致伤心和气馁，但是社区会记住你的反应， +即使很久以后他们已经忘记了谁的补丁真正被合并。 diff --git a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst index 956815edbd18..57beca02181c 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/ - http://git-scm.com/ + https://www.kernel.org/pub/software/scm/git/docs/user-manual.html - http://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上获得一个帐户，但这些帐户并不容易找到；有关更多信息， -请参阅 http://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/）。 +（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更改等。所有类型 +的检查，只要它们能引导更好的代码进入内核，都是受欢迎和值得的。 diff --git a/Documentation/translations/zh_CN/process/8.Conclusion.rst b/Documentation/translations/zh_CN/process/8.Conclusion.rst index 2bbd76161e10..643b88af97bb 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,55 @@ ======== 关于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>` 也是所有内核开发人员都应该阅读的内容。许多内部内核API都是使用kerneldoc机制 -记录的；“make htmldocs”或“make pdfdocs”可用于以HTML或PDF格式生成这些文档（ -尽管某些发行版提供的tex版本会遇到内部限制，无法正确处理文档）。 +记录的；“make htmldocs”或“make pdfdocs”可用于以HTML或PDF格式生成这些文档 +（尽管某些发行版提供的tex版本会遇到内部限制，无法正确处理文档）。 -不同的网站在各个细节层次上讨论内核开发。您的作者想谦虚地建议用 http://lwn.net/ -作为来源；有关许多特定内核主题的信息可以通过以下网址的lwn内核索引找到： +不同的网站在各个细节层次上讨论内核开发。本文作者想谦虚地建议用 https://lwn.net/ +作为来源；有关许多特定内核主题的信息可以通过以下网址的 LWN 内核索引找到： - http://lwn.net/kernel/index/ + http://lwn.net/kernel/index/ 除此之外，内核开发人员的一个宝贵资源是： - http://kernelnewbies.org/ + https://kernelnewbies.org/ -当然，我们不应该忘记 http://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的文档，请访问： - http://www.kernel.org/pub/software/scm/git/docs/ + https://www.kernel.org/pub/software/scm/git/docs/ - http://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生态系统中的大多数其他参与者可以通过为内核做出贡献而受益。使 代码进入主线是提高代码质量、降低维护和分发成本、提高对内核开发方向的影响程度 -等的关键。这是一种人人都赢的局面。踢开你的编辑，来加入我们吧，你会非常受 -欢迎的。 +等的关键。这是一种共赢的局面。启动你的编辑器，来加入我们吧；你会非常受欢迎的。 diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index 4f6237392e65..fa28ef0a7fee 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -1,21 +1,23 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/coding-style.rst <codingstyle>` +:Original: Documentation/process/coding-style.rst .. _cn_codingstyle: -译者:: +:译者: + - 张乐 Zhang Le <r0bertz@gentoo.org> + - Andy Deng <theandy.deng@gmail.com> + - 吴想成 <bobwxc@email.cn> - 中文版维护者： 张乐 Zhang Le <r0bertz@gentoo.org> - 中文版翻译者： 张乐 Zhang Le <r0bertz@gentoo.org> - 中文版校译者： 王聪 Wang Cong <xiyou.wangcong@gmail.com> - wheelz <kernel.zeng@gmail.com> - 管旭东 Xudong Guan <xudong.guan@gmail.com> - Li Zefan <lizf@cn.fujitsu.com> - Wang Chen <wangchen@cn.fujitsu.com> +:校译: + - 王聪 Wang Cong <xiyou.wangcong@gmail.com> + - wheelz <kernel.zeng@gmail.com> + - 管旭东 Xudong Guan <xudong.guan@gmail.com> + - Li Zefan <lizf@cn.fujitsu.com> + - Wang Chen <wangchen@cn.fujitsu.com> Linux 内核代码风格 -========================= +================== 这是一个简短的文档，描述了 linux 内核的首选代码风格。代码风格是因人而异的， 而且我不愿意把自己的观点强加给任何人，但这就像我去做任何事情都必须遵循的原则 @@ -29,7 +31,7 @@ Linux 内核代码风格 1) 缩进 --------------- +------- 制表符是 8 个字符，所以缩进也是 8 个字符。有些异端运动试图将缩进变为 4 (甚至 2！) 字符深，这几乎相当于尝试将圆周率的值定义为 3。 @@ -61,7 +63,7 @@ Linux 内核代码风格 case 'K': case 'k': mem <<= 10; - /* fall through */ + fallthrough; default: break; } @@ -73,6 +75,22 @@ Linux 内核代码风格 if (condition) do_this; do_something_everytime; +不要使用逗号来避免使用大括号： + +.. code-block:: c + + if (condition) + do_this(), do_that(); + +使用大括号包裹多语句： + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } + 也不要在一行里放多个赋值语句。内核代码风格超级简单。就是避免可能导致别人误读 的表达式。 @@ -83,20 +101,25 @@ Linux 内核代码风格 2) 把长的行和字符串打散 ------------------------------- +----------------------- 代码风格的意义就在于使用平常使用的工具来维持代码的可读性和可维护性。 每一行的长度的限制是 80 列，我们强烈建议您遵守这个惯例。 长于 80 列的语句要打散成有意义的片段。除非超过 80 列能显著增加可读性，并且不 -会隐藏信息。子片段要明显短于母片段，并明显靠右。这同样适用于有着很长参数列表 -的函数头。然而，绝对不要打散对用户可见的字符串，例如 printk 信息，因为这样就 +会隐藏信息。 + +子片段要明显短于母片段，并明显靠右。一种非常常用的样式是将子体与函数左括号对齐。 + +这同样适用于有着很长参数列表的函数头。 + +然而，绝对不要打散对用户可见的字符串，例如 printk 信息，因为这样就 很难对它们 grep。 3) 大括号和空格的放置 ------------------------------- +--------------------- C 语言风格中另外一个常见问题是大括号的放置。和缩进大小不同，选择或弃用某种放 置策略并没有多少技术上的原因，不过首选的方式，就像 Kernighan 和 Ritchie 展示 @@ -132,12 +155,12 @@ C 语言风格中另外一个常见问题是大括号的放置。和缩进大小 body of function } -全世界的异端可能会抱怨这个不一致性是... 呃... 不一致的，不过所有思维健全的人 +全世界的异端可能会抱怨这个不一致性是……呃……不一致，不过所有思维健全的人 都知道 (a) K&R 是 **正确的** 并且 (b) K&R 是正确的。此外，不管怎样函数都是特 殊的 (C 函数是不能嵌套的)。 注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是 do 语 -句中的 "while" 或者 if 语句中的 "else"，像这样： +句中的 ``while`` 或者 if 语句中的 ``else`` ，像这样： .. code-block:: c @@ -191,7 +214,7 @@ C 语言风格中另外一个常见问题是大括号的放置。和缩进大小 } 3.1) 空格 -******************** +********* Linux 内核的空格使用方式 (主要) 取决于它是用于函数还是关键字。(大多数) 关键字 后要加一个空格。值得注意的例外是 sizeof, typeof, alignof 和 __attribute__，这 @@ -254,7 +277,7 @@ Linux 内核的空格使用方式 (主要) 取决于它是用于函数还是关 4) 命名 ------------------------------- +------- C 是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pascal 程序员不同， C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字。C 程序员会 @@ -268,19 +291,38 @@ C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字 ``count_active_users()`` 或者类似的名字，你不应该叫它 ``cntuser()`` 。 在函数名中包含函数类型 (所谓的匈牙利命名法) 是脑子出了问题——编译器知道那些类 -型而且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题 -的程序。 +型而且能够检查那些类型，这样做只能把程序员弄糊涂了。 本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计 数器，它应该被称为 ``i`` 。叫它 ``loop_counter`` 并无益处，如果它没有被误解的 可能的话。类似的， ``tmp`` 可以用来称呼任意类型的临时变量。 如果你怕混淆了你的本地变量名，你就遇到另一个问题了，叫做函数增长荷尔蒙失衡综 -合症。请看第六章 (函数)。 +合征。请看第六章 (函数)。 +对于符号名称和文档，避免引入新的“master/slave”（或独立于“master”的“slave”） +和“blacklist/whitelist”。 + +“master/slave”推荐替换为： + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader/follower' + 'director/performer' + +“blacklist/whitelist”推荐替换为： + 'denylist/allowlist' + 'blocklist/passlist' + +引入新用法的例外情况是：维护用户空间ABI/API，或更新现有（截至2020年）硬件或 +协议规范的代码时要求这些术语。对于新规范，尽可能将术语的规范用法转换为内核 +编码标准。 + +.. warning:: + 以上主从、黑白名单规则不适用于中文文档，请勿更改中文术语！ 5) Typedef ------------ +---------- 不要使用类似 ``vps_t`` 之类的东西。 @@ -309,7 +351,7 @@ C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字 .. note:: - 不透明性和 "访问函数" 本身是不好的。我们使用 pte_t 等类型的原因在于真 + 不透明性和“访问函数”本身是不好的。我们使用 pte_t 等类型的原因在于真 的是完全没有任何共用的可访问信息。 (b) 清楚的整数类型，如此，这层抽象就可以 **帮助** 消除到底是 ``int`` 还是 @@ -354,7 +396,7 @@ C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字 6) 函数 ------------------------------- +------- 函数应该简短而漂亮，并且只完成一件事情。函数应该可以一屏或者两屏显示完 (我们 都知道 ISO/ANSI 屏幕大小是 80x24)，只做一件事情，而且把它做好。 @@ -384,12 +426,46 @@ C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字 } EXPORT_SYMBOL(system_is_up); -在函数原型中，包含函数名和它们的数据类型。虽然 C 语言里没有这样的要求，在 +6.1) 函数原型 +************* + +在函数原型中包含参数名和它们的数据类型。虽然 C 语言里没有这样的要求，但在 Linux 里这是提倡的做法，因为这样可以很简单的给读者提供更多的有价值的信息。 +不要在函数声明里使用 ``extern`` 关键字，因为这会导致代码行变长，并且不是严格 +必需的。 + +写函数原型时，请保持 `元素顺序规则 <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_ 。 +例如下列函数声明:: + + __init void * __must_check action(enum magic value, size_t size, u8 count, + char *fmt, ...) __printf(4, 5) __malloc; + +推荐的函数原型元素顺序是： + +- 储存类型（下方的 ``static __always_inline`` ，注意 ``__always_inline`` + 技术上来讲是个属性但被当做 ``inline`` ） +- 储存类型属性（上方的 ``__init`` ——即节声明，但也像 ``__cold`` ） +- 返回类型（上方的 ``void *`` ） +- 返回类型属性（上方的 ``__must_check`` ） +- 函数名（上方的 ``action`` ） +- 函数参数（上方的 ``(enum magic value, size_t size, u8 count, char *fmt, ...)`` ， + 注意必须写上参数名） +- 函数参数属性（上方的 ``__printf(4, 5)`` ） +- 函数行为属性（上方的 ``__malloc`` ） + +请注意，对于函数 **定义** （即实际函数体），编译器不允许在函数参数之后添加函 +数参数属性。在这种情况下，它们应该跟随存储类型属性（例如，与上面的 **声明** +示例相比，请注意下面的 ``__printf(4, 5)`` 的位置发生了变化）:: + + static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value, + size_t size, u8 count, char *fmt, ...) __malloc + { + ... + } 7) 集中的函数退出途径 ------------------------------- +--------------------- 虽然被某些人声称已经过时，但是 goto 语句的等价物还是经常被编译器所使用，具体 形式是无条件跳转指令。 @@ -433,7 +509,7 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供 return result; } -一个需要注意的常见错误是 ``一个 err 错误`` ，就像这样： +一个需要注意的常见错误是 ``单 err 错误`` ，就像这样： .. code-block:: c @@ -457,19 +533,19 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供 8) 注释 ------------------------------- +------- 注释是好的，不过有过度注释的危险。永远不要在注释里解释你的代码是如何运作的： 更好的做法是让别人一看你的代码就可以明白，解释写的很差的代码是浪费时间。 -一般的，你想要你的注释告诉别人你的代码做了什么，而不是怎么做的。也请你不要把 +一般来说你用注释告诉别人你的代码做了什么，而不是怎么做的。也请你不要把 注释放在一个函数体内部：如果函数复杂到你需要独立的注释其中的一部分，你很可能 需要回到第六章看一看。你可以做一些小注释来注明或警告某些很聪明 (或者槽糕) 的 做法，但不要加太多。你应该做的，是把注释放在函数的头部，告诉人们它做了什么， 也可以加上它做这些事情的原因。 -当注释内核 API 函数时，请使用 kernel-doc 格式。请看 -Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 +当注释内核 API 函数时，请使用 kernel-doc 格式。详见 +Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。 长 (多行) 注释的首选风格是： @@ -501,17 +577,18 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 9) 你已经把事情弄糟了 ------------------------------- +--------------------- -这没什么，我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你 +这没什么，我们都是这样。可能你长期使用 Unix 的朋友已经告诉你 ``GNU emacs`` 能自动帮你格式化 C 源代码，而且你也注意到了，确实是这样，不过它 所使用的默认值和我们想要的相去甚远 (实际上，甚至比随机打的还要差——无数个猴子 -在 GNU emacs 里打字永远不会创造出一个好程序) (译注：Infinite Monkey Theorem) +在 GNU emacs 里打字永远不会创造出一个好程序) +*(译注：Infinite Monkey Theorem)* 所以你要么放弃 GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案， 你可以把下面这段粘贴到你的 .emacs 文件里。 -.. code-block:: none +.. code-block:: elisp (defun c-lineup-arglist-tabs-only (ignored) "Line up argument lists by tabs, not spaces" @@ -530,7 +607,7 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 (c-offsets-alist . ( (arglist-close . c-lineup-arglist-tabs-only) (arglist-cont-nonempty . - (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) (arglist-intro . +) (brace-list-intro . +) (c . c-lineup-C-comments) @@ -574,9 +651,14 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 ``indent`` 有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册。 不过记住： ``indent`` 不能修正坏的编程习惯。 +请注意，您还可以使用 ``clang-format`` 工具帮助您处理这些规则，快速自动重新格 +式化部分代码，并审阅整个文件以发现代码风格错误、打字错误和可能的改进。它还可 +以方便地排序 ``#include`` ，对齐变量/宏，重排文本和其他类似任务。 +详见 Documentation/process/clang-format.rst 。 + 10) Kconfig 配置文件 ------------------------------- +-------------------- 对于遍布源码树的所有 Kconfig* 配置文件来说，它们缩进方式有所不同。紧挨着 ``config`` 定义的行，用一个制表符缩进，然而 help 信息的缩进则额外增加 2 个空 @@ -599,11 +681,11 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 depends on ADFS_FS ... -要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.rst。 +要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.rst 。 11) 数据结构 ------------------------------- +------------ 如果一个数据结构，在创建和销毁它的单线执行环境之外可见，那么它必须要有一个引 用计数器。内核里没有垃圾收集 (并且内核之外的垃圾收集慢且效率低下)，这意味着你 @@ -627,7 +709,7 @@ mm_count)，和文件系统 (``struct super_block``: s_count 和 s_active) 中 12) 宏，枚举和RTL ------------------------------- +----------------- 用于定义常量的宏的名字及枚举里的标签需要大写。 @@ -639,7 +721,7 @@ mm_count)，和文件系统 (``struct super_block``: s_count 和 s_active) 中 宏的名字请用大写字母，不过形如函数的宏的名字可以用小写字母。 -一般的，如果能写成内联函数就不要写成像函数的宏。 +通常如果能写成内联函数就不要写成像函数的宏。 含有多个语句的宏应该被包含在一个 do-while 代码块里： @@ -697,18 +779,18 @@ mm_count)，和文件系统 (``struct super_block``: s_count 和 s_active) 中 (ret); \ }) -ret 是本地变量的通用名字 - __foo_ret 更不容易与一个已存在的变量冲突。 +ret 是本地变量的通用名字—— __foo_ret 更不容易与一个已存在的变量冲突。 cpp 手册对宏的讲解很详细。gcc internals 手册也详细讲解了 RTL，内核里的汇编语 言经常用到它。 13) 打印内核消息 ------------------------------- +---------------- -内核开发者应该是受过良好教育的。请一定注意内核信息的拼写，以给人以好的印象。 +内核开发者应该看起来有文化。请一定注意内核信息的拼写，以给人良好的印象。 不要用不规范的单词比如 ``dont``，而要用 ``do not`` 或者 ``don't`` 。保证这些信 -息简单明了,无歧义。 +息简单明了、无歧义。 内核信息不必以英文句号结束。 @@ -725,17 +807,18 @@ dev_info() 等等。对于那些不和某个特定设备相关连的信息，<li 或设定了 CONFIG_DYNAMIC_DEBUG。实际这同样是为了 dev_dbg()，一个相关约定是在一 个已经开启了 DEBUG 时，使用 VERBOSE_DEBUG 来添加 dev_vdbg()。 -许多子系统拥有 Kconfig 调试选项来开启 -DDEBUG 在对应的 Makefile 里面；在其他 +许多子系统拥有 Kconfig 调试选项来开启对应 Makefile 里面的 -DDEBUG；在其他 情况下，特殊文件使用 #define DEBUG。当一条调试信息需要被无条件打印时，例如， 如果已经包含一个调试相关的 #ifdef 条件，printk(KERN_DEBUG ...) 就可被使用。 14) 分配内存 ------------------------------- +------------ 内核提供了下面的一般用途的内存分配函数： kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() 和 vzalloc()。 -请参考 API 文档以获取有关它们的详细信息。 +请参考 API 文档以获取有关它们的详细信息： +Documentation/translations/zh_CN/core-api/memory-allocation.rst 。 传递结构体大小的首选形式是这样的： @@ -762,11 +845,13 @@ kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() 和 vzalloc()。 p = kcalloc(n, sizeof(...), ...); -两种形式检查分配大小 n * sizeof(...) 的溢出，如果溢出返回 NULL。 +两种形式都会检查分配 n * sizeof(...) 大小时内存的溢出，如果溢出返回 NULL。 +在没有 __GFP_NOWARN 的情况下使用时，这些通用分配函数都会在失败时发起堆栈转储， +因此当返回NULL时，没有必要发出额外的失败消息。 15) 内联弊病 ------------------------------- +------------ 有一个常见的误解是 ``内联`` 是 gcc 提供的可以让代码运行更快的一个选项。虽然使 用内联函数有时候是恰当的 (比如作为一种替代宏的方式，请看第十二章)，不过很多情 @@ -787,7 +872,7 @@ inline gcc 也可以自动使其内联。而且其他用户可能会要求移除 16) 函数返回值及命名 ------------------------------- +-------------------- 函数可以返回多种不同类型的值，最常见的一种是表明函数执行成功或者失败的值。这样 的一个值可以表示为一个错误代码整数 (-Exxx＝失败，0＝成功) 或者一个 ``成功`` @@ -798,7 +883,7 @@ inline gcc 也可以自动使其内联。而且其他用户可能会要求移除 产生这种 bug，请遵循下面的惯例:: 如果函数的名字是一个动作或者强制性的命令，那么这个函数应该返回错误代 - 码整数。如果是一个判断，那么函数应该返回一个 "成功" 布尔值。 + 码整数。如果是一个判断，那么函数应该返回一个“成功”布尔值。 比如， ``add work`` 是一个命令，所以 add_work() 在成功时返回 0，在失败时返回 -EBUSY。类似的，因为 ``PCI device present`` 是一个判断，所以 pci_dev_present() @@ -807,13 +892,35 @@ inline gcc 也可以自动使其内联。而且其他用户可能会要求移除 所有 EXPORTed 函数都必须遵守这个惯例，所有的公共函数也都应该如此。私有 (static) 函数不需要如此，但是我们也推荐这样做。 -返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。一般的， +返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。通常 他们通过返回一些正常值范围之外的结果来表示出错。典型的例子是返回指针的函数， 他们使用 NULL 或者 ERR_PTR 机制来报告错误。 +17) 使用布尔类型 +---------------- + +Linux内核布尔（bool）类型是C99 _Bool类型的别名。布尔值只能为0或1，而对布尔的 +隐式或显式转换将自动将值转换为true或false。在使用布尔类型时 **不需要** 构造， +它会消除一类错误。 + +使用布尔值时，应使用true和false定义，而不是1和0。 -17) 不要重新发明内核宏 ------------------------------- +布尔函数返回类型和堆栈变量总是可以在适当的时候使用。鼓励使用布尔来提高可读性， +并且布尔值在存储时通常比“int”更好。 + +如果缓存行布局或值的大小很重要，请不要使用布尔，因为其大小和对齐方式根据编译 +的体系结构而不同。针对对齐和大小进行优化的结构体不应使用布尔。 + +如果一个结构体有多个true/false值，请考虑将它们合并为具有1比特成员的位域，或使 +用适当的固定宽度类型，如u8。 + +类似地，对于函数参数，多个true/false值可以合并为单个按位的“标志”参数，如果调 +用点具有裸true/false常量，“标志”参数通常是更具可读性的替代方法。 + +总之，在结构体和参数中有限地使用布尔可以提高可读性。 + +18) 不要重新发明内核宏 +---------------------- 头文件 include/linux/kernel.h 包含了一些宏，你应该使用它们，而不要自己写一些 它们的变种。比如，如果你需要计算一个数组的长度，使用这个宏 @@ -826,18 +933,18 @@ inline gcc 也可以自动使其内联。而且其他用户可能会要求移除 .. code-block:: c - #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) + #define sizeof_field(t, f) (sizeof(((t*)0)->f)) 还有可以做严格的类型检查的 min() 和 max() 宏，如果你需要可以使用它们。你可以 自己看看那个头文件里还定义了什么你可以拿来用的东西，如果有定义的话，你就不应 在你的代码里自己重新定义。 -18) 编辑器模式行和其他需要罗嗦的事情 --------------------------------------------------- +19) 编辑器模式行和其他需要罗嗦的事情 +------------------------------------ 有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如，emacs -能够解释被标记成这样的行： +能够解析被标记成这样的行： .. code-block:: c @@ -853,7 +960,7 @@ inline gcc 也可以自动使其内联。而且其他用户可能会要求移除 End: */ -Vim 能够解释这样的标记： +Vim 能够解析这样的标记： .. code-block:: c @@ -864,8 +971,8 @@ Vim 能够解释这样的标记： 的模式，或者使用其他可以产生正确的缩进的巧妙方法。 -19) 内联汇编 ------------------------------- +20) 内联汇编 +------------ 在特定架构的代码中，你可能需要内联汇编与 CPU 和平台相关功能连接。需要这么做时 就不要犹豫。然而，当 C 可以完成工作时，不要平白无故地使用内联汇编。在可能的情 @@ -881,8 +988,8 @@ Vim 能够解释这样的标记： 移除了。你不必总是这样做，尽管，这不必要的举动会限制优化。 在写一个包含多条指令的单个内联汇编语句时，把每条指令用引号分割而且各占一行， -除了最后一条指令外，在每个指令结尾加上 \n\t，让汇编输出时可以正确地缩进下一条 -指令： +除了最后一条指令外，在每个指令结尾加上 ``\n\t`` ，让汇编输出时可以正确地缩进 +下一条指令： .. code-block:: c @@ -891,10 +998,10 @@ Vim 能够解释这样的标记： : /* outputs */ : /* inputs */ : /* clobbers */); -20) 条件编译 ------------------------------- +21) 条件编译 +------------ -只要可能，就不要在 .c 文件里面使用预处理条件 (#if, #ifdef)；这样做让代码更难 +只要可能，就不要在 .c 文件里面使用预处理条件 (#if, #ifdef)；这样做会让代码更难 阅读并且更难去跟踪逻辑。替代方案是，在头文件中用预处理条件提供给那些 .c 文件 使用，再给 #else 提供一个空桩 (no-op stub) 版本，然后在 .c 文件内无条件地调用 那些 (定义在头文件内的) 函数。这样做，编译器会避免为桩函数 (stub) 的调用生成 @@ -905,8 +1012,8 @@ Vim 能够解释这样的标记： 条件到这个辅助函数内。 如果你有一个在特定配置中，可能变成未使用的函数或变量，编译器会警告它定义了但 -未使用，把它标记为 __maybe_unused 而不是将它包含在一个预处理条件中。(然而，如 -果一个函数或变量总是未使用，就直接删除它。) +未使用，请把它标记为 __maybe_unused 而不是将它包含在一个预处理条件中。(然而， +如果一个函数或变量总是未使用，就直接删除它。) 在代码中，尽可能地使用 IS_ENABLED 宏来转化某个 Kconfig 标记为 C 的布尔 表达式，并在一般的 C 条件中使用它： @@ -932,23 +1039,45 @@ Vim 能够解释这样的标记： #endif /* CONFIG_SOMETHING */ -附录 I) 参考 -------------------- +附录 I) 参考资料 +---------------- -The C Programming Language, 第二版 +The C Programming Language, 2nd Edition 作者：Brian W. Kernighan 和 Denni M. Ritchie. Prentice Hall, Inc., 1988. -ISBN 0-13-110362-8 (软皮), 0-13-110370-9 (硬皮). +ISBN 0-13-110362-8 (平装), 0-13-110370-9 (精装). + +.. note:: + + 《C程序设计语言（第2版）》 + 作者：[美] Brian W. Kernighan / [美] Dennis M. Ritchie + 译者：徐宝文 / 李志 / 尤晋元（审校） + 出版社：机械工业出版社，2019 + ISBN：9787111617945 The Practice of Programming 作者：Brian W. Kernighan 和 Rob Pike. Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. +.. note:: + + 《程序设计实践》 + 作者：[美] Brian W. Kernighan / [美] Rob Pike + 出版社：机械工业出版社，2005 + ISBN：9787111091578 + + 《程序设计实践》 + 作者：[美] Brian W. Kernighan / Rob Pike + 译者：裘宗燕 + 出版社：机械工业出版社，2000 + ISBN：9787111075738 + GNU 手册 - 遵循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent, -都可以从 http://www.gnu.org/manual/ 找到 +都可以从 https://www.gnu.org/manual/ 找到 WG14 是 C 语言的国际标准化工作组，URL: http://www.open-std.org/JTC1/SC22/WG14/ -Kernel process/coding-style.rst，作者 greg@kroah.com 发表于 OLS 2002： +内核文档 Documentation/process/coding-style.rst， +作者 greg@kroah.com 发表于 OLS 2002： http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/zh_CN/process/development-process.rst b/Documentation/translations/zh_CN/process/development-process.rst index 30cffe66c075..c10d8e2e21eb 100644 --- a/Documentation/translations/zh_CN/process/development-process.rst +++ b/Documentation/translations/zh_CN/process/development-process.rst @@ -8,9 +8,10 @@ 内核开发过程指南 ================ -内容: +本文档的目的是帮助开发人员（及其经理）以最小的挫折感与开发社区合作。它试图记录这个社区如何以一种不熟悉Linux内核开发（或者实际上是自由软件开发）的人可以访问的方式工作。虽然这里有一些技术资料，但这是一个面向过程的讨论，不需要深入了解内核编程就可以理解。 .. toctree:: + :caption: 内容 :numbered: :maxdepth: 2 @@ -22,5 +23,3 @@ 6.Followthrough 7.AdvancedTopics 8.Conclusion - -本文档的目的是帮助开发人员（及其经理）以最小的挫折感与开发社区合作。它试图记录这个社区如何以一种不熟悉Linux内核开发（或者实际上是自由软件开发）的人可以访问的方式工作。虽然这里有一些技术资料，但这是一个面向过程的讨论，不需要深入了解内核编程就可以理解。 diff --git a/Documentation/translations/zh_CN/process/email-clients.rst b/Documentation/translations/zh_CN/process/email-clients.rst index 102023651118..34d51cdadc7b 100644 --- a/Documentation/translations/zh_CN/process/email-clients.rst +++ b/Documentation/translations/zh_CN/process/email-clients.rst @@ -1,17 +1,20 @@ -.. _cn_email_clients: +.. SPDX-License-Identifier: GPL-2.0-or-later .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/email-clients.rst <email_clients>` +.. _cn_email_clients: -译者:: +:Original: Documentation/process/email-clients.rst - 中文版维护者： 贾威威 Harry Wei <harryxiyou@gmail.com> - 中文版翻译者： 贾威威 Harry Wei <harryxiyou@gmail.com> - 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> - 中文版校译者： Yinglin Luan <synmyth@gmail.com> - Xiaochen Wang <wangxiaochen0@gmail.com> - yaxinsn <yaxinsn@163.com> +:译者: + - 贾威威 Harry Wei <harryxiyou@gmail.com> + - 时奎亮 Alex Shi <alexs@kernel.org> + - 吴想成 Wu XiangCheng <bobwxc@email.cn> + +:校译: + - Yinglin Luan <synmyth@gmail.com> + - Xiaochen Wang <wangxiaochen0@gmail.com> + - yaxinsn <yaxinsn@163.com> Linux邮件客户端配置信息 ======================= @@ -27,12 +30,17 @@ Git 改日志。如果工作正常，再将补丁发送到相应的邮件列表。 -普通配置 +通用配置 -------- + Linux内核补丁是通过邮件被提交的，最好把补丁作为邮件体的内嵌文本。有些维护者 接收附件，但是附件的内容格式应该是"text/plain"。然而，附件一般是不赞成的， 因为这会使补丁的引用部分在评论过程中变的很困难。 +同时也强烈建议在补丁或其他邮件的正文中使用纯文本格式。https://useplaintext.email +有助于了解如何配置你喜欢的邮件客户端，并在您还没有首选的情况下列出一些推荐的 +客户端。 + 用来发送Linux内核补丁的邮件客户端在发送补丁时应该处于文本的原始状态。例如， 他们不能改变或者删除制表符或者空格，甚至是在每一行的开头或者结尾。 @@ -40,17 +48,17 @@ Linux内核补丁是通过邮件被提交的，最好把补丁作为邮件体的 不要让你的邮件客户端进行自动换行。这样也会破坏你的补丁。 -邮件客户端不能改变文本的字符集编码方式。要发送的补丁只能是ASCII或者UTF-8编码方式， -如果你使用UTF-8编码方式发送邮件，那么你将会避免一些可能发生的字符集问题。 +邮件客户端不能改变文本的字符集编码方式。要发送的补丁只能是ASCII或者UTF-8编码 +方式，如果你使用UTF-8编码方式发送邮件，那么你将会避免一些可能发生的字符集问题。 -邮件客户端应该形成并且保持 References: 或者 In-Reply-To: 标题，那么 -邮件话题就不会中断。 +邮件客户端应该生成并且保持“References:”或者“In-Reply-To:”邮件头，这样邮件会话 +就不会中断。 -复制粘帖(或者剪贴粘帖)通常不能用于补丁，因为制表符会转换为空格。使用xclipboard, xclip -或者xcutsel也许可以，但是最好测试一下或者避免使用复制粘帖。 +复制粘帖(或者剪贴粘帖)通常不能用于补丁，因为制表符会转换为空格。使用xclipboard, +xclip或者xcutsel也许可以，但是最好测试一下或者避免使用复制粘帖。 -不要在使用PGP/GPG署名的邮件中包含补丁。这样会使得很多脚本不能读取和适用于你的补丁。 -（这个问题应该是可以修复的） +不要在使用PGP/GPG签名的邮件中包含补丁。这样会使得很多脚本不能读取和适用于你的 +补丁。（这个问题应该是可以修复的） 在给内核邮件列表发送补丁之前，给自己发送一个补丁是个不错的主意，保存接收到的 邮件，将补丁用'patch'命令打上，如果成功了，再给内核邮件列表发送。 @@ -58,98 +66,133 @@ Linux内核补丁是通过邮件被提交的，最好把补丁作为邮件体的 一些邮件客户端提示 ------------------ + 这里给出一些详细的MUA配置提示，可以用于给Linux内核发送补丁。这些并不意味是 所有的软件包配置总结。 说明： -TUI = 以文本为基础的用户接口 -GUI = 图形界面用户接口 + +- TUI = 以文本为基础的用户接口 +- GUI = 图形界面用户接口 Alpine (TUI) -~~~~~~~~~~~~ +************ 配置选项： -在"Sending Preferences"部分： -- "Do Not Send Flowed Text"必须开启 -- "Strip Whitespace Before Sending"必须关闭 +在 :menuselection:`Sending Preferences` 菜单： + +- :menuselection:`Do Not Send Flowed Text` 必须开启 +- :menuselection:`Strip Whitespace Before Sending` 必须关闭 + +当写邮件时，光标应该放在补丁会出现的地方，然后按下 :kbd:`CTRL-R` 组合键，使指 +定的补丁文件嵌入到邮件中。 + +Claws Mail (GUI) +**************** + +可以用，有人用它成功地发过补丁。 -当写邮件时，光标应该放在补丁会出现的地方，然后按下CTRL-R组合键，使指定的 -补丁文件嵌入到邮件中。 +用 :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`) 或外置编辑器插入补丁。 + +若要在Claws编辑窗口重修改插入的补丁，需关闭 +:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` +的 `Auto wrapping` 。 Evolution (GUI) -~~~~~~~~~~~~~~~ +*************** -一些开发者成功的使用它发送补丁 +一些开发者成功的使用它发送补丁。 -当选择邮件选项：Preformat - 从Format->Heading->Preformatted (Ctrl-7)或者工具栏 +撰写邮件时： +从 :menuselection:`格式-->段落样式-->预格式化` (:kbd:`CTRL-7`) +或工具栏选择 :menuselection:`预格式化` ； 然后使用： - Insert->Text File... (Alt-n x)插入补丁文件。 +:menuselection:`插入-->文本文件...` (:kbd:`ALT-N x`) 插入补丁文件。 -你还可以"diff -Nru old.c new.c | xclip"，选择Preformat，然后使用中间键进行粘帖。 +你还可以 ``diff -Nru old.c new.c | xclip`` ，选择 :menuselection:`预格式化` ， +然后使用鼠标中键进行粘帖。 Kmail (GUI) -~~~~~~~~~~~ +*********** 一些开发者成功的使用它发送补丁。 -默认设置不为HTML格式是合适的；不要启用它。 +默认撰写设置禁用HTML格式是合适的；不要启用它。 -当书写一封邮件的时候，在选项下面不要选择自动换行。唯一的缺点就是你在邮件中输入的任何文本 -都不会被自动换行，因此你必须在发送补丁之前手动换行。最简单的方法就是启用自动换行来书写邮件， -然后把它保存为草稿。一旦你在草稿中再次打开它，它已经全部自动换行了，那么你的邮件虽然没有 -选择自动换行，但是还不会失去已有的自动换行。 +当书写一封邮件的时候，在选项下面不要选择自动换行。唯一的缺点就是你在邮件中输 +入的任何文本都不会被自动换行，因此你必须在发送补丁之前手动换行。最简单的方法 +就是启用自动换行来书写邮件，然后把它保存为草稿。一旦你在草稿中再次打开它，它 +已经全部自动换行了，那么你的邮件虽然没有选择自动换行，但是还不会失去已有的自 +动换行。 -在邮件的底部，插入补丁之前，放上常用的补丁定界符：三个连字号(---)。 +在邮件的底部，插入补丁之前，放上常用的补丁定界符：三个连字符(``---``)。 -然后在"Message"菜单条目，选择插入文件，接着选取你的补丁文件。还有一个额外的选项，你可以 -通过它配置你的邮件建立工具栏菜单，还可以带上"insert file"图标。 +然后在 :menuselection:`信件` 菜单，选择 :menuselection:`插入文本文件` ，接 +着选取你的补丁文件。还有一个额外的选项，你可以通过它配置你的创建新邮件工具栏， +加上 :menuselection:`插入文本文件` 图标。 -你可以安全地通过GPG标记附件，但是内嵌补丁最好不要使用GPG标记它们。作为内嵌文本的签发补丁， -当从GPG中提取7位编码时会使他们变的更加复杂。 +将编辑器窗口拉到足够宽避免折行。对于KMail 1.13.5 (KDE 4.5.4)，它会在发送邮件 +时对编辑器窗口中显示折行的地方自动换行。在选项菜单中取消自动换行仍不能解决。 +因此，如果你的补丁中有非常长的行，必须在发送之前把编辑器窗口拉得非常宽。 +参见：https://bugs.kde.org/show_bug.cgi?id=174034 -如果你非要以附件的形式发送补丁，那么就右键点击附件，然后选中属性，突出"Suggest automatic -display"，这样内嵌附件更容易让读者看到。 +你可以安全地用GPG签名附件，但是内嵌补丁最好不要使用GPG签名它们。作为内嵌文本 +插入的签名补丁将使其难以从7-bit编码中提取。 -当你要保存将要发送的内嵌文本补丁，你可以从消息列表窗格选择包含补丁的邮件，然后右击选择 -"save as"。你可以使用一个没有更改的包含补丁的邮件，如果它是以正确的形式组成。当你正真在它 -自己的窗口之下察看，那时没有选项可以保存邮件--已经有一个这样的bug被汇报到了kmail的bugzilla -并且希望这将会被处理。邮件是以只针对某个用户可读写的权限被保存的，所以如果你想把邮件复制到其他地方， -你不得不把他们的权限改为组或者整体可读。 +如果你非要以附件的形式发送补丁，那么就右键点击附件，然后选择 +:menuselection:`属性` ，打开 :menuselection:`建议自动显示` ，使附件内联更容 +易让读者看到。 + +当你要保存将要发送的内嵌文本补丁，你可以从消息列表窗格选择包含补丁的邮件，然 +后右键选择 :menuselection:`另存为` 。如果整个电子邮件的组成正确，您可直接将 +其作为补丁使用。电子邮件以当前用户可读写权限保存，因此您必须 ``chmod`` ，以 +使其在复制到别处时用户组和其他人可读。 Lotus Notes (GUI) -~~~~~~~~~~~~~~~~~ +***************** 不要使用它。 +IBM Verse (Web GUI) +******************* + +同上条。 + Mutt (TUI) -~~~~~~~~~~ +********** + +很多Linux开发人员使用mutt客户端，这证明它肯定工作得非常漂亮。 -很多Linux开发人员使用mutt客户端，所以证明它肯定工作的非常漂亮。 +Mutt不自带编辑器，所以不管你使用什么编辑器，不自动断行就行。大多数编辑器都有 +:menuselection:`插入文件` 选项，它可以在不改变文件内容的情况下插入文件。 -Mutt不自带编辑器，所以不管你使用什么编辑器都不应该带有自动断行。大多数编辑器都带有 -一个"insert file"选项，它可以通过不改变文件内容的方式插入文件。 +用 ``vim`` 作为mutt的编辑器:: -'vim'作为mutt的编辑器： set editor="vi" - 如果使用xclip，敲入以下命令 +如果使用xclip，敲入以下命令:: + :set paste - 按中键之前或者shift-insert或者使用 + +然后再按中键或者shift-insert或者使用:: + :r filename -如果想要把补丁作为内嵌文本。 -(a)ttach工作的很好，不带有"set paste"。 +把补丁插入为内嵌文本。 +在未设置 ``set paste`` 时(a)ttach工作的很好。 你可以通过 ``git format-patch`` 生成补丁，然后用 Mutt发送它们:: - $ mutt -H 0001-some-bug-fix.patch + $ mutt -H 0001-some-bug-fix.patch 配置选项： + 它应该以默认设置的形式工作。 -然而，把"send_charset"设置为"us-ascii::utf-8"也是一个不错的主意。 +然而，把 ``send_charset`` 设置一下也是一个不错的主意:: + + set send_charset="us-ascii:utf-8" Mutt 是高度可配置的。 这里是个使用mutt通过 Gmail 发送的补丁的最小配置:: @@ -178,71 +221,107 @@ Mutt 是高度可配置的。 这里是个使用mutt通过 Gmail 发送的补丁 set from = "username@gmail.com" set use_from = yes -Mutt文档含有更多信息: +Mutt文档含有更多信息： - http://dev.mutt.org/trac/wiki/UseCases/Gmail + https://gitlab.com/muttmua/mutt/-/wikis/UseCases/Gmail - http://dev.mutt.org/doc/manual.html + http://www.mutt.org/doc/manual/ Pine (TUI) -~~~~~~~~~~ +********** Pine过去有一些空格删减问题，但是这些现在应该都被修复了。 -如果可以，请使用alpine(pine的继承者) +如果可以，请使用alpine（pine的继承者）。 配置选项： -- 最近的版本需要消除流程文本 -- "no-strip-whitespace-before-send"选项也是需要的。 + +- 最近的版本需要 ``quell-flowed-text`` +- ``no-strip-whitespace-before-send`` 选项也是需要的。 Sylpheed (GUI) -~~~~~~~~~~~~~~ +************** - 内嵌文本可以很好的工作（或者使用附件）。 - 允许使用外部的编辑器。 -- 对于目录较多时非常慢。 +- 收件箱较多时非常慢。 - 如果通过non-SSL连接，无法使用TLS SMTP授权。 -- 在组成窗口中有一个很有用的ruler bar。 -- 给地址本中添加地址就不会正确的了解显示名。 +- 撰写窗口的标尺很有用。 +- 将地址添加到通讯簿时无法正确理解显示的名称。 Thunderbird (GUI) -~~~~~~~~~~~~~~~~~ +***************** + +Thunderbird是Outlook的克隆版本，它很容易损坏文本，但也有一些方法强制修正。 + +在完成修改后（包括安装扩展），您需要重新启动Thunderbird。 + +- 允许使用外部编辑器： + + 使用Thunderbird发补丁最简单的方法是使用扩展来打开您最喜欢的外部编辑器。 + + 下面是一些能够做到这一点的扩展样例。 + + - “External Editor Revived” + + https://github.com/Frederick888/external-editor-revived + + https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/ + + 它需要安装“本地消息主机（native messaging host）”。 + 参见以下文档: + https://github.com/Frederick888/external-editor-revived/wiki + + - “External Editor” + + https://github.com/exteditor/exteditor + + 下载并安装此扩展，然后打开 :menuselection:`新建消息` 窗口, 用 + :menuselection:`查看-->工具栏-->自定义...` 给它增加一个按钮，直接点击此 + 按钮即可使用外置编辑器。 + + 请注意，“External Editor”要求你的编辑器不能fork，换句话说，编辑器必须在 + 关闭前不返回。你可能需要传递额外的参数或修改编辑器设置。最值得注意的是， + 如果您使用的是gvim，那么您必须将 :menuselection:`external editor` 设置的 + 编辑器字段设置为 ``/usr/bin/gvim --nofork"`` （假设可执行文件在 + ``/usr/bin`` ），以传递 ``-f`` 参数。如果您正在使用其他编辑器，请阅读其 + 手册了解如何处理。 -默认情况下，thunderbird很容易损坏文本，但是还有一些方法可以强制它变得更好。 +若要修正内部编辑器，请执行以下操作： -- 在用户帐号设置里，组成和寻址，不要选择"Compose messages in HTML format"。 +- 修改你的Thunderbird设置，不要使用 ``format=flowed`` ！ + 回到主窗口，按照 + :menuselection:`主菜单-->首选项-->常规-->配置编辑器...` + 打开Thunderbird的配置编辑器。 -- 编辑你的Thunderbird配置设置来使它不要拆行使用：user_pref("mailnews.wraplength", 0); + - 将 ``mailnews.send_plaintext_flowed`` 设为 ``false`` -- 编辑你的Thunderbird配置设置，使它不要使用"format=flowed"格式：user_pref("mailnews. - send_plaintext_flowed", false); + - 将 ``mailnews.wraplength`` 从 ``72`` 改为 ``0`` -- 你需要使Thunderbird变为预先格式方式： - 如果默认情况下你书写的是HTML格式，那不是很难。仅仅从标题栏的下拉框中选择"Preformat"格式。 - 如果默认情况下你书写的是文本格式，你不得把它改为HTML格式（仅仅作为一次性的）来书写新的消息， - 然后强制使它回到文本格式，否则它就会拆行。要实现它，在写信的图标上使用shift键来使它变为HTML - 格式，然后标题栏的下拉框中选择"Preformat"格式。 +- 不要写HTML邮件！ + 回到主窗口，打开 + :menuselection:`主菜单-->账户设置-->你的@邮件.地址-->通讯录/编写&地址簿` ， + 关掉 ``以HTML格式编写消息`` 。 -- 允许使用外部的编辑器： - 针对Thunderbird打补丁最简单的方法就是使用一个"external editor"扩展，然后使用你最喜欢的 - $EDITOR来读取或者合并补丁到文本中。要实现它，可以下载并且安装这个扩展，然后添加一个使用它的 - 按键View->Toolbars->Customize...最后当你书写信息的时候仅仅点击它就可以了。 +- 只用纯文本格式查看邮件！ + 回到主窗口， :menuselection:`主菜单-->查看-->消息体为-->纯文本` ！ TkRat (GUI) -~~~~~~~~~~~ +*********** 可以使用它。使用"Insert file..."或者外部的编辑器。 Gmail (Web GUI) -~~~~~~~~~~~~~~~ +*************** 不要使用它发送补丁。 Gmail网页客户端自动地把制表符转换为空格。 -虽然制表符转换为空格问题可以被外部编辑器解决，同时它还会使用回车换行把每行拆分为78个字符。 +虽然制表符转换为空格问题可以被外部编辑器解决，但它同时还会使用回车换行把每行 +拆分为78个字符。 -另一个问题是Gmail还会把任何不是ASCII的字符的信息改为base64编码。它把东西变的像欧洲人的名字。 +另一个问题是Gmail还会把任何含有非ASCII的字符的消息改用base64编码，如欧洲人的 +名字。 - ### diff --git a/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst b/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst new file mode 100644 index 000000000000..cf5f1fca3d92 --- /dev/null +++ b/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst @@ -0,0 +1,228 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/embargoed-hardware-issues.rst <embargoed_hardware_issues>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +被限制的硬件问题 +================ + +范围 +---- + +导致安全问题的硬件问题与只影响Linux内核的纯软件错误是不同的安全错误类别。 + +必须区别对待诸如熔毁(Meltdown)、Spectre、L1TF等硬件问题，因为它们通常会影响 +所有操作系统（“OS”），因此需要在不同的OS供应商、发行版、硬件供应商和其他各方 +之间进行协调。对于某些问题，软件缓解可能依赖于微码或固件更新，这需要进一步的 +协调。 + +.. _zh_Contact: + +接触 +---- + +Linux内核硬件安全小组独立于普通的Linux内核安全小组。 + +该小组只负责协调被限制的硬件安全问题。Linux内核中纯软件安全漏洞的报告不由该 +小组处理，报告者将被引导至常规Linux内核安全小组(:ref:`Documentation/admin-guide/ +<securitybugs>`)联系。 + +可以通过电子邮件 <hardware-security@kernel.org> 与小组联系。这是一份私密的安全 +官名单，他们将帮助您根据我们的文档化流程协调问题。 + +邮件列表是加密的，发送到列表的电子邮件可以通过PGP或S/MIME加密，并且必须使用报告 +者的PGP密钥或S/MIME证书签名。该列表的PGP密钥和S/MIME证书可从 +https://www.kernel.org/.... 获得。 + +虽然硬件安全问题通常由受影响的硬件供应商处理，但我们欢迎发现潜在硬件缺陷的研究 +人员或个人与我们联系。 + +硬件安全官 +^^^^^^^^^^ + +目前的硬件安全官小组: + + - Linus Torvalds（Linux基金会院士） + - Greg Kroah Hartman（Linux基金会院士） + - Thomas Gleixner（Linux基金会院士） + +邮件列表的操作 +^^^^^^^^^^^^^^ + +处理流程中使用的加密邮件列表托管在Linux Foundation的IT基础设施上。通过提供这项 +服务，Linux基金会的IT基础设施安全总监在技术上有能力访问被限制的信息，但根据他 +的雇佣合同，他必须保密。Linux基金会的IT基础设施安全总监还负责 kernel.org 基础 +设施。 + +Linux基金会目前的IT基础设施安全总监是 Konstantin Ryabitsev。 + +保密协议 +-------- + +Linux内核硬件安全小组不是正式的机构，因此无法签订任何保密协议。核心社区意识到 +这些问题的敏感性，并提供了一份谅解备忘录。 + +谅解备忘录 +---------- + +Linux内核社区深刻理解在不同操作系统供应商、发行商、硬件供应商和其他各方之间 +进行协调时，保持硬件安全问题处于限制状态的要求。 + +Linux内核社区在过去已经成功地处理了硬件安全问题，并且有必要的机制允许在限制 +限制下进行符合社区的开发。 + +Linux内核社区有一个专门的硬件安全小组负责初始联系，并监督在限制规则下处理 +此类问题的过程。 + +硬件安全小组确定开发人员（领域专家），他们将组成特定问题的初始响应小组。最初 +的响应小组可以引入更多的开发人员（领域专家）以最佳的技术方式解决这个问题。 + +所有相关开发商承诺遵守限制规定，并对收到的信息保密。违反承诺将导致立即从当前 +问题中排除，并从所有相关邮件列表中删除。此外，硬件安全小组还将把违反者排除在 +未来的问题之外。这一后果的影响在我们社区是一种非常有效的威慑。如果发生违规 +情况，硬件安全小组将立即通知相关方。如果您或任何人发现潜在的违规行为，请立即 +向硬件安全人员报告。 + +流程 +^^^^ + +由于Linux内核开发的全球分布式特性，面对面的会议几乎不可能解决硬件安全问题。 +由于时区和其他因素，电话会议很难协调，只能在绝对必要时使用。加密电子邮件已被 +证明是解决此类问题的最有效和最安全的通信方法。 + +开始披露 +"""""""" + +披露内容首先通过电子邮件联系Linux内核硬件安全小组。此初始联系人应包含问题的 +描述和任何已知受影响硬件的列表。如果您的组织制造或分发受影响的硬件，我们建议 +您也考虑哪些其他硬件可能会受到影响。 + +硬件安全小组将提供一个特定于事件的加密邮件列表，用于与报告者进行初步讨论、 +进一步披露和协调。 + +硬件安全小组将向披露方提供一份开发人员（领域专家）名单，在与开发人员确认他们 +将遵守本谅解备忘录和文件化流程后，应首先告知开发人员有关该问题的信息。这些开发 +人员组成初始响应小组，并在初始接触后负责处理问题。硬件安全小组支持响应小组， +但不一定参与缓解开发过程。 + +虽然个别开发人员可能通过其雇主受到保密协议的保护，但他们不能以Linux内核开发 +人员的身份签订个别保密协议。但是，他们将同意遵守这一书面程序和谅解备忘录。 + +披露方应提供已经或应该被告知该问题的所有其他实体的联系人名单。这有几个目的: + + - 披露的实体列表允许跨行业通信，例如其他操作系统供应商、硬件供应商等。 + + - 可联系已披露的实体，指定应参与缓解措施开发的专家。 + + - 如果需要处理某一问题的专家受雇于某一上市实体或某一上市实体的成员，则响应 + 小组可要求该实体披露该专家。这确保专家也是实体反应小组的一部分。 + +披露 +"""" + +披露方通过特定的加密邮件列表向初始响应小组提供详细信息。 + +根据我们的经验，这些问题的技术文档通常是一个足够的起点，最好通过电子邮件进行 +进一步的技术澄清。 + +缓解开发 +"""""""" + +初始响应小组设置加密邮件列表，或在适当的情况下重新修改现有邮件列表。 + +使用邮件列表接近于正常的Linux开发过程，并且在过去已经成功地用于为各种硬件安全 +问题开发缓解措施。 + +邮件列表的操作方式与正常的Linux开发相同。发布、讨论和审查修补程序，如果同意， +则应用于非公共git存储库，参与开发人员只能通过安全连接访问该存储库。存储库包含 +针对主线内核的主开发分支，并根据需要为稳定的内核版本提供向后移植分支。 + +最初的响应小组将根据需要从Linux内核开发人员社区中确定更多的专家。引进专家可以 +在开发过程中的任何时候发生，需要及时处理。 + +如果专家受雇于披露方提供的披露清单上的实体或其成员，则相关实体将要求其参与。 + +否则，披露方将被告知专家参与的情况。谅解备忘录涵盖了专家，要求披露方确认参与。 +如果披露方有令人信服的理由提出异议，则必须在五个工作日内提出异议，并立即与事件 +小组解决。如果披露方在五个工作日内未作出回应，则视为默许。 + +在确认或解决异议后，专家由事件小组披露，并进入开发过程。 + +协调发布 +"""""""" + +有关各方将协商限制结束的日期和时间。此时，准备好的缓解措施集成到相关的内核树中 +并发布。 + +虽然我们理解硬件安全问题需要协调限制时间，但限制时间应限制在所有有关各方制定、 +测试和准备缓解措施所需的最短时间内。人为地延长限制时间以满足会议讨论日期或其他 +非技术原因，会给相关的开发人员和响应小组带来了更多的工作和负担，因为补丁需要 +保持最新，以便跟踪正在进行的上游内核开发，这可能会造成冲突的更改。 + +CVE分配 +""""""" + +硬件安全小组和初始响应小组都不分配CVE，开发过程也不需要CVE。如果CVE是由披露方 +提供的，则可用于文档中。 + +流程专使 +-------- + +为了协助这一进程，我们在各组织设立了专使，他们可以回答有关报告流程和进一步处理 +的问题或提供指导。专使不参与特定问题的披露，除非响应小组或相关披露方提出要求。 +现任专使名单: + + ============= ======================================================== + ARM + AMD Tom Lendacky <thomas.lendacky@amd.com> + IBM + Intel Tony Luck <tony.luck@intel.com> + Qualcomm Trilok Soni <tsoni@codeaurora.org> + + Microsoft Sasha Levin <sashal@kernel.org> + VMware + Xen Andrew Cooper <andrew.cooper3@citrix.com> + + Canonical John Johansen <john.johansen@canonical.com> + Debian Ben Hutchings <ben@decadent.org.uk> + Oracle Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> + Red Hat Josh Poimboeuf <jpoimboe@redhat.com> + SUSE Jiri Kosina <jkosina@suse.cz> + + Amazon + Google Kees Cook <keescook@chromium.org> + ============= ======================================================== + +如果要将您的组织添加到专使名单中，请与硬件安全小组联系。被提名的专使必须完全 +理解和支持我们的过程，并且在Linux内核社区中很容易联系。 + +加密邮件列表 +------------ + +我们使用加密邮件列表进行通信。这些列表的工作原理是，发送到列表的电子邮件使用 +列表的PGP密钥或列表的/MIME证书进行加密。邮件列表软件对电子邮件进行解密，并 +使用订阅者的PGP密钥或S/MIME证书为每个订阅者分别对其进行重新加密。有关邮件列表 +软件和用于确保列表安全和数据保护的设置的详细信息，请访问: +https://www.kernel.org/.... + +关键点 +^^^^^^ + +初次接触见 :ref:`zh_Contact`. 对于特定于事件的邮件列表，密钥和S/MIME证书通过 +特定列表发送的电子邮件传递给订阅者。 + +订阅事件特定列表 +^^^^^^^^^^^^^^^^ + +订阅由响应小组处理。希望参与通信的披露方将潜在订户的列表发送给响应组，以便 +响应组可以验证订阅请求。 + +每个订户都需要通过电子邮件向响应小组发送订阅请求。电子邮件必须使用订阅服务器 +的PGP密钥或S/MIME证书签名。如果使用PGP密钥，则必须从公钥服务器获得该密钥， +并且理想情况下该密钥连接到Linux内核的PGP信任网。另请参见: +https://www.kernel.org/signature.html. + +响应小组验证订阅者，并将订阅者添加到列表中。订阅后，订阅者将收到来自邮件列表 +的电子邮件，该邮件列表使用列表的PGP密钥或列表的/MIME证书签名。订阅者的电子邮件 +客户端可以从签名中提取PGP密钥或S/MIME证书，以便订阅者可以向列表发送加密电子 +邮件。 diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst index a8e6ab818983..cc47be356dd3 100644 --- a/Documentation/translations/zh_CN/process/howto.rst +++ b/Documentation/translations/zh_CN/process/howto.rst @@ -45,7 +45,7 @@ Linux内核大部分是由C语言写成的，一些体系结构相关的代码 - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] 《C语言参考手册（原书第5版）》（邱仲潘 等译）[机械工业出版社] -Linux内核使用GNU C和GNU工具链开发。虽然它遵循ISO C89标准，但也用到了一些 +Linux内核使用GNU C和GNU工具链开发。虽然它遵循ISO C11标准，但也用到了一些 标准中没有定义的扩展。内核是自给自足的C环境，不依赖于标准C库的支持，所以 并不支持C标准中的部分定义。比如long long类型的大数除法和浮点运算就不允许 使用。有时候确实很难弄清楚内核对工具链的要求和它所使用的扩展，不幸的是目 @@ -69,7 +69,7 @@ Linux内核源代码都是在GPL（通用公共许可证）的保护下发布的 邮件组里的人并不是律师，不要期望他们的话有法律效力。 对于GPL的常见问题和解答，请访问以下链接： - http://www.gnu.org/licenses/gpl-faq.html + https://www.gnu.org/licenses/gpl-faq.html 文档 @@ -96,7 +96,6 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 的代码。 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` - :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` 这两份文档明确描述如何创建和发送补丁，其中包括（但不仅限于)： - 邮件内容 @@ -109,7 +108,7 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 其他关于如何正确地生成补丁的优秀文档包括： "The Perfect Patch" - http://www.ozlabs.org/~akpm/stuff/tpp.txt + https://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" @@ -126,7 +125,7 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 这篇文档对于理解Linux的开发哲学至关重要。对于将开发平台从其他操作系 统转移到Linux的人来说也很重要。 - :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` + :ref:`Documentation/process/security-bugs.rst <securitybugs>` 如果你认为自己发现了Linux内核的安全性问题，请根据这篇文档中的步骤来 提醒其他内核开发者并帮助解决这个问题。 @@ -163,7 +162,7 @@ ReST格式的文档会生成在 Documentation/output. 目录中。 ------------------ 如果你对Linux内核开发一无所知，你应该访问“Linux内核新手”计划： - http://kernelnewbies.org + https://kernelnewbies.org 它拥有一个可以问各种最基本的内核开发问题的邮件列表（在提问之前一定要记得 查找已往的邮件，确认是否有人已经回答过相同的问题）。它还拥有一个可以获得 @@ -176,7 +175,7 @@ ReST格式的文档会生成在 Documentation/output. 目录中。 如果你想加入内核开发社区并协助完成一些任务，却找不到从哪里开始，可以访问 “Linux内核房管员”计划： - http://kernelnewbies.org/KernelJanitors + https://kernelnewbies.org/KernelJanitors 这是极佳的起点。它提供一个相对简单的任务列表，列出内核代码中需要被重新 整理或者改正的地方。通过和负责这个计划的开发者们一同工作，你会学到将补丁 @@ -212,7 +211,7 @@ ReST格式的文档会生成在 Documentation/output. 目录中。 - 每当一个新版本的内核被发布，为期两周的集成窗口将被打开。在这段时间里 维护者可以向Linus提交大段的修改，通常这些修改已经被放到-mm内核中几个 星期了。提交大量修改的首选方式是使用git工具（内核的代码版本管理工具 - ，更多的信息可以在 http://git-scm.com/ 获取），不过使用普通补丁也是 + ，更多的信息可以在 https://git-scm.com/ 获取），不过使用普通补丁也是 可以的。 - 两个星期以后-rc1版本内核发布。之后只有不包含可能影响整个内核稳定性的 新功能的补丁才可能被接受。请注意一个全新的驱动程序（或者文件系统）有 @@ -252,10 +251,10 @@ Linux-next 集成测试树 在将子系统树的更新合并到主线树之前，需要对它们进行集成测试。为此，存在一个 特殊的测试存储库，其中几乎每天都会提取所有子系统树： - https://git.kernel.org/？p=linux/kernel/git/next/linux-next.git + https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git 通过这种方式，Linux-next 对下一个合并阶段将进入主线内核的内容给出了一个概要 -展望。非常欢冒险的测试者运行测试Linux-next。 +展望。非常欢迎冒险的测试者运行测试Linux-next。 多个主要版本的稳定版内核树 ----------------------------------- @@ -307,7 +306,7 @@ bugzilla.kernel.org是Linux内核开发者们用来跟踪内核Bug的网站。 网上很多地方都有这个邮件列表的存档(archive)。可以使用搜索引擎来找到这些 存档。比如： - http://dir.gmane.org/gmane.linux.kernel + https://lore.kernel.org/lkml/ 在发信之前，我们强烈建议你先在存档中搜索你想要讨论的问题。很多已经被详细 讨论过的问题只在邮件列表的存档中可以找到。 @@ -381,7 +380,7 @@ MAINTAINERS文件中可以找到不同话题对应的邮件列表。 内核社区的工作模式同大多数传统公司开发队伍的工作模式并不相同。下面这些例 子，可以帮助你避免某些可能发生问题： -用这些话介绍你的修改提案会有好处： +用这些话介绍你的修改提案会有好处：（在任何时候你都不应该用中文写提案） - 它同时解决了多个问题 - 它删除了2000行代码 @@ -448,8 +447,8 @@ Linux内核社区并不喜欢一下接收大段的代码。修改需要被恰当 保证修改分成很多小块，这样在整个项目都准备好被包含进内核之前，其中的一部 分可能会先被接收。 -必须了解这样做是不可接受的：试图将未完成的工作提交进内核，然后再找时间修 -复。 +你必须明白这么做是无法令人接受的：试图将不完整的代码提交进内核，然后再找 +时间修复。 证明修改的必要性 @@ -472,11 +471,11 @@ Linux内核社区并不喜欢一下接收大段的代码。修改需要被恰当 想了解它具体应该看起来像什么，请查阅以下文档中的“ChangeLog”章节： “The Perfect Patch” - http://www.ozlabs.org/~akpm/stuff/tpp.txt + https://www.ozlabs.org/~akpm/stuff/tpp.txt -这些事情有时候做起来很难。要在任何方面都做到完美可能需要好几年时间。这是 -一个持续提高的过程，它需要大量的耐心和决心。只要不放弃，你一定可以做到。 +这些事情有时候做起来很难。想要在任何方面都做到完美可能需要好几年时间。这 +是一个持续提高的过程，它需要大量的耐心和决心。只要不放弃，你一定可以做到。 很多人已经做到了，而他们都曾经和现在的你站在同样的起点上。 diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst index be1e764a80d2..3ca02d281be0 100644 --- a/Documentation/translations/zh_CN/process/index.rst +++ b/Documentation/translations/zh_CN/process/index.rst @@ -5,32 +5,53 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/index.rst <process_index>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> +:Original: Documentation/process/index.rst -.. _cn_process_index: +:翻译: + Alex Shi <alex.shi@linux.alibaba.com> + +======================== 与Linux 内核社区一起工作 ======================== -那么你想成为Linux内核开发人员？ 欢迎！ 不但从技术意义上讲有很多关于内核的知识 -需要学，而且了解我们社区的工作方式也很重要。 阅读这些文章可以让您以更轻松地, -麻烦最少的方式将更改合并到内核。 +你想成为Linux内核开发人员吗？欢迎之至！在学习许多关于内核的技术知识的同时， +了解我们社区的工作方式也很重要。阅读这些文档可以让您以更轻松的、麻烦更少的 +方式将更改合并到内核。 -以下是每位开发人员应阅读的基本指南。 +以下是每位开发人员都应阅读的基本指南： .. toctree:: :maxdepth: 1 + license-rules howto code-of-conduct code-of-conduct-interpretation + development-process submitting-patches programming-language coding-style - development-process + maintainer-pgp-guide email-clients - license-rules + kernel-enforcement-statement + kernel-driver-statement + +TODOLIST: + +* handling-regressions +* maintainer-handbooks + +安全方面, 请阅读: + +.. toctree:: + :maxdepth: 1 + + embargoed-hardware-issues + +TODOLIST: + +* security-bugs 其它大多数开发人员感兴趣的社区指南： @@ -38,19 +59,38 @@ .. toctree:: :maxdepth: 1 - submitting-drivers - submit-checklist stable-api-nonsense - stable-kernel-rules management-style + stable-kernel-rules + submit-checklist + +TODOLIST: + +* changes +* kernel-docs +* deprecated +* maintainers +* researcher-guidelines +* contribution-maturity-model -这些是一些总体技术指南，由于缺乏更好的地方，现在已经放在这里 + +这些是一些总体性技术指南，由于不大好分类而放在这里： .. toctree:: :maxdepth: 1 magic-number volatile-considered-harmful + ../arch/riscv/patch-acceptance + ../core-api/unaligned-memory-access + +TODOLIST: + +* applying-patches +* backporting +* adding-syscalls +* botching-up-ioctls +* clang-format .. only:: subproject and html diff --git a/Documentation/translations/zh_CN/process/kernel-driver-statement.rst b/Documentation/translations/zh_CN/process/kernel-driver-statement.rst new file mode 100644 index 000000000000..2b3375bcccfd --- /dev/null +++ b/Documentation/translations/zh_CN/process/kernel-driver-statement.rst @@ -0,0 +1,199 @@ +.. _cn_process_statement_driver: + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/kernel-driver-statement.rst <process_statement_driver>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +内核驱动声明 +------------ + +关于Linux内核模块的立场声明 +=========================== + +我们，以下署名的Linux内核开发人员，认为任何封闭源Linux内核模块或驱动程序都是 +有害的和不可取的。我们已经一再发现它们对Linux用户，企业和更大的Linux生态系统 +有害。这样的模块否定了Linux开发模型的开放性，稳定性，灵活性和可维护性，并使 +他们的用户无法使用Linux社区的专业知识。提供闭源内核模块的供应商迫使其客户 +放弃Linux的主要优势或选择新的供应商。因此，为了充分利用开源所提供的成本节省和 +共享支持优势，我们敦促供应商采取措施，以开源内核代码在Linux上为其客户提供支持。 + +我们只为自己说话，而不是我们今天可能会为之工作，过去或将来会为之工作的任何公司。 + + - Dave Airlie + - Nick Andrew + - Jens Axboe + - Ralf Baechle + - Felipe Balbi + - Ohad Ben-Cohen + - Muli Ben-Yehuda + - Jiri Benc + - Arnd Bergmann + - Thomas Bogendoerfer + - Vitaly Bordug + - James Bottomley + - Josh Boyer + - Neil Brown + - Mark Brown + - David Brownell + - Michael Buesch + - Franck Bui-Huu + - Adrian Bunk + - François Cami + - Ralph Campbell + - Luiz Fernando N. Capitulino + - Mauro Carvalho Chehab + - Denis Cheng + - Jonathan Corbet + - Glauber Costa + - Alan Cox + - Magnus Damm + - Ahmed S. Darwish + - Robert P. J. Day + - Hans de Goede + - Arnaldo Carvalho de Melo + - Helge Deller + - Jean Delvare + - Mathieu Desnoyers + - Sven-Thorsten Dietrich + - Alexey Dobriyan + - Daniel Drake + - Alex Dubov + - Randy Dunlap + - Michael Ellerman + - Pekka Enberg + - Jan Engelhardt + - Mark Fasheh + - J. Bruce Fields + - Larry Finger + - Jeremy Fitzhardinge + - Mike Frysinger + - Kumar Gala + - Robin Getz + - Liam Girdwood + - Jan-Benedict Glaw + - Thomas Gleixner + - Brice Goglin + - Cyrill Gorcunov + - Andy Gospodarek + - Thomas Graf + - Krzysztof Halasa + - Harvey Harrison + - Stephen Hemminger + - Michael Hennerich + - Tejun Heo + - Benjamin Herrenschmidt + - Kristian Høgsberg + - Henrique de Moraes Holschuh + - Marcel Holtmann + - Mike Isely + - Takashi Iwai + - Olof Johansson + - Dave Jones + - Jesper Juhl + - Matthias Kaehlcke + - Kenji Kaneshige + - Jan Kara + - Jeremy Kerr + - Russell King + - Olaf Kirch + - Roel Kluin + - Hans-Jürgen Koch + - Auke Kok + - Peter Korsgaard + - Jiri Kosina + - Aaro Koskinen + - Mariusz Kozlowski + - Greg Kroah-Hartman + - Michael Krufky + - Aneesh Kumar + - Clemens Ladisch + - Christoph Lameter + - Gunnar Larisch + - Anders Larsen + - Grant Likely + - John W. Linville + - Yinghai Lu + - Tony Luck + - Pavel Machek + - Matt Mackall + - Paul Mackerras + - Roland McGrath + - Patrick McHardy + - Kyle McMartin + - Paul Menage + - Thierry Merle + - Eric Miao + - Akinobu Mita + - Ingo Molnar + - James Morris + - Andrew Morton + - Paul Mundt + - Oleg Nesterov + - Luca Olivetti + - S.Çağlar Onur + - Pierre Ossman + - Keith Owens + - Venkatesh Pallipadi + - Nick Piggin + - Nicolas Pitre + - Evgeniy Polyakov + - Richard Purdie + - Mike Rapoport + - Sam Ravnborg + - Gerrit Renker + - Stefan Richter + - David Rientjes + - Luis R. Rodriguez + - Stefan Roese + - Francois Romieu + - Rami Rosen + - Stephen Rothwell + - Maciej W. Rozycki + - Mark Salyzyn + - Yoshinori Sato + - Deepak Saxena + - Holger Schurig + - Amit Shah + - Yoshihiro Shimoda + - Sergei Shtylyov + - Kay Sievers + - Sebastian Siewior + - Rik Snel + - Jes Sorensen + - Alexey Starikovskiy + - Alan Stern + - Timur Tabi + - Hirokazu Takata + - Eliezer Tamir + - Eugene Teo + - Doug Thompson + - FUJITA Tomonori + - Dmitry Torokhov + - Marcelo Tosatti + - Steven Toth + - Theodore Tso + - Matthias Urlichs + - Geert Uytterhoeven + - Arjan van de Ven + - Ivo van Doorn + - Rik van Riel + - Wim Van Sebroeck + - Hans Verkuil + - Horst H. von Brand + - Dmitri Vorobiev + - Anton Vorontsov + - Daniel Walker + - Johannes Weiner + - Harald Welte + - Matthew Wilcox + - Dan J. Williams + - Darrick J. Wong + - David Woodhouse + - Chris Wright + - Bryan Wu + - Rafael J. Wysocki + - Herbert Xu + - Vlad Yasevich + - Peter Zijlstra + - Bartlomiej Zolnierkiewicz diff --git a/Documentation/translations/zh_CN/process/kernel-enforcement-statement.rst b/Documentation/translations/zh_CN/process/kernel-enforcement-statement.rst new file mode 100644 index 000000000000..75f7b7b9137c --- /dev/null +++ b/Documentation/translations/zh_CN/process/kernel-enforcement-statement.rst @@ -0,0 +1,151 @@ +.. _cn_process_statement_kernel: + +.. include:: ../disclaimer-zh_CN.rst + +:Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>` +:Translator: Alex Shi <alex.shi@linux.alibaba.com> + +Linux 内核执行声明 +------------------ + +作为Linux内核的开发人员，我们对如何使用我们的软件以及如何实施软件许可证有着 +浓厚的兴趣。遵守GPL-2.0的互惠共享义务对我们软件和社区的长期可持续性至关重要。 + +虽然有权强制执行对我们社区的贡献中的单独版权权益，但我们有共同的利益，即确保 +个人强制执行行动的方式有利于我们的社区，不会对我们软件生态系统的健康和增长 +产生意外的负面影响。为了阻止无益的执法行动，我们同意代表我们自己和我们版权 +利益的任何继承人对Linux内核用户作出以下符合我们开发社区最大利益的承诺: + + 尽管有GPL-2.0的终止条款，我们同意，采用以下GPL-3.0条款作为我们许可证下的 + 附加许可，作为任何对许可证下权利的非防御性主张，这符合我们开发社区的最佳 + 利益。 + + 但是，如果您停止所有违反本许可证的行为，则您从特定版权持有人处获得的 + 许可证将被恢复：（a）暂时恢复，除非版权持有人明确并最终终止您的许可证； + 以及（b）永久恢复, 如果版权持有人未能在你终止违反后60天内以合理方式 + 通知您违反本许可证的行为，则永久恢复您的许可证。 + + 此外，如果版权所有者以某种合理的方式通知您违反了本许可，这是您第一次 + 从该版权所有者处收到违反本许可的通知（对于任何作品），并且您在收到通知 + 后的30天内纠正违规行为。则您从特定版权所有者处获得的许可将永久恢复. + +我们提供这些保证的目的是鼓励更多地使用该软件。我们希望公司和个人使用、修改和 +分发此软件。我们希望以公开和透明的方式与用户合作，以消除我们对法规遵从性或强制 +执行的任何不确定性，这些不确定性可能会限制我们软件的采用。我们将法律行动视为 +最后手段，只有在其他社区努力未能解决这一问题时才采取行动。 + +最后，一旦一个不合规问题得到解决，我们希望用户会感到欢迎，加入我们为之努力的 +这个项目。共同努力，我们会更强大。 + +除了下面提到的以外，我们只为自己说话，而不是为今天、过去或将来可能为之工作的 +任何公司说话。 + + - Laura Abbott + - Bjorn Andersson (Linaro) + - Andrea Arcangeli + - Neil Armstrong + - Jens Axboe + - Pablo Neira Ayuso + - Khalid Aziz + - Ralf Baechle + - Felipe Balbi + - Arnd Bergmann + - Ard Biesheuvel + - Tim Bird + - Paolo Bonzini + - Christian Borntraeger + - Mark Brown (Linaro) + - Paul Burton + - Javier Martinez Canillas + - Rob Clark + - Kees Cook (Google) + - Jonathan Corbet + - Dennis Dalessandro + - Vivien Didelot (Savoir-faire Linux) + - Hans de Goede + - Mel Gorman (SUSE) + - Sven Eckelmann + - Alex Elder (Linaro) + - Fabio Estevam + - Larry Finger + - Bhumika Goyal + - Andy Gross + - Juergen Gross + - Shawn Guo + - Ulf Hansson + - Stephen Hemminger (Microsoft) + - Tejun Heo + - Rob Herring + - Masami Hiramatsu + - Michal Hocko + - Simon Horman + - Johan Hovold (Hovold Consulting AB) + - Christophe JAILLET + - Olof Johansson + - Lee Jones (Linaro) + - Heiner Kallweit + - Srinivas Kandagatla + - Jan Kara + - Shuah Khan (Samsung) + - David Kershner + - Jaegeuk Kim + - Namhyung Kim + - Colin Ian King + - Jeff Kirsher + - Greg Kroah-Hartman (Linux Foundation) + - Christian König + - Vinod Koul + - Krzysztof Kozlowski + - Viresh Kumar + - Aneesh Kumar K.V + - Julia Lawall + - Doug Ledford + - Chuck Lever (Oracle) + - Daniel Lezcano + - Shaohua Li + - Xin Long + - Tony Luck + - Catalin Marinas (Arm Ltd) + - Mike Marshall + - Chris Mason + - Paul E. McKenney + - Arnaldo Carvalho de Melo + - David S. Miller + - Ingo Molnar + - Kuninori Morimoto + - Trond Myklebust + - Martin K. Petersen (Oracle) + - Borislav Petkov + - Jiri Pirko + - Josh Poimboeuf + - Sebastian Reichel (Collabora) + - Guenter Roeck + - Joerg Roedel + - Leon Romanovsky + - Steven Rostedt (VMware) + - Frank Rowand + - Ivan Safonov + - Anna Schumaker + - Jes Sorensen + - K.Y. Srinivasan + - David Sterba (SUSE) + - Heiko Stuebner + - Jiri Kosina (SUSE) + - Willy Tarreau + - Dmitry Torokhov + - Linus Torvalds + - Thierry Reding + - Rik van Riel + - Luis R. Rodriguez + - Geert Uytterhoeven (Glider bvba) + - Eduardo Valentin (Amazon.com) + - Daniel Vetter + - Linus Walleij + - Richard Weinberger + - Dan Williams + - Rafael J. Wysocki + - Arvind Yadav + - Masahiro Yamada + - Wei Yongjun + - Lv Zheng + - Marc Zyngier (Arm Ltd) diff --git a/Documentation/translations/zh_CN/process/magic-number.rst b/Documentation/translations/zh_CN/process/magic-number.rst index e4c225996af0..4e4aeaca796c 100644 --- a/Documentation/translations/zh_CN/process/magic-number.rst +++ b/Documentation/translations/zh_CN/process/magic-number.rst @@ -1,150 +1,82 @@ -.. _cn_magicnumbers: - .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/magic-number.rst <magicnumbers>` +:Original: Documentation/process/magic-number.rst + +:翻译: -如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 -以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者:: + 贾威威 Jia Wei Wei <harryxiyou@gmail.com> - 中文版维护者： 贾威威 Jia Wei Wei <harryxiyou@gmail.com> - 中文版翻译者： 贾威威 Jia Wei Wei <harryxiyou@gmail.com> - 中文版校译者： 贾威威 Jia Wei Wei <harryxiyou@gmail.com> +:校译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> Linux 魔术数 ============ -这个文件是有关当前使用的魔术值注册表。当你给一个结构添加了一个魔术值，你也应该把这个魔术值添加到这个文件，因为我们最好把用于各种结构的魔术值统一起来。 +这个文件是有关当前使用的魔术值注册表。当你给一个结构体添加了一个魔术值，你也 +应该把这个魔术值添加到这个文件，因为我们最好把用于各种结构体的魔术值统一起来。 -使用魔术值来保护内核数据结构是一个非常好的主意。这就允许你在运行期检查(a)一个结构是否已经被攻击，或者(b)你已经给一个例行程序通过了一个错误的结构。后一种情况特别地有用---特别是当你通过一个空指针指向结构体的时候。tty源码，例如，经常通过特定驱动使用这种方法并且反复地排列特定方面的结构。 +使用魔术值来保护内核数据结构是一个 **非常好的主意** 。这就允许你在运行时检 +查一个结构体(a)是否已经被攻击，或者(b)你已经给一个例程传递了一个错误的结构 +体。最后一种情况特别地有用---特别是当你通过一个空指针指向结构体的时候。例如， +tty源码经常通过特定驱动使用这种方法用来反复地排列特定方面的结构体。 -使用魔术值的方法是在结构的开始处声明的，如下:: +使用魔术值的方法是在结构体的开头声明它们，如下:: struct tty_ldisc { int magic; ... }; -当你以后给内核添加增强功能的时候，请遵守这条规则！这样就会节省数不清的调试时间，特别是一些古怪的情况，例如，数组超出范围并且重新写了超出部分。遵守这个规则，这些情况可以被快速地，安全地避免。 +当你以后给内核添加增强功能的时候，请遵守这条规则！这样就会节省数不清的调试 +时间，特别是一些古怪的情况，例如，数组超出范围并且覆盖写了超出部分。利用这 +个规则，这些情况可以被快速地，安全地检测到这些案例。 + +变更日志:: - Theodore Ts'o - 31 Mar 94 + Theodore Ts'o + 31 Mar 94 -给当前的Linux 2.1.55添加魔术表。 + 给当前的Linux 2.1.55添加魔术表。 - Michael Chastain - <mailto:mec@shout.net> - 22 Sep 1997 + Michael Chastain + <mailto:mec@shout.net> + 22 Sep 1997 -现在应该最新的Linux 2.1.112.因为在特性冻结期间，不能在2.2.x前改变任何东西。这些条目被数域所排序。 + 现在应该最新的Linux 2.1.112.因为在特性冻结期间，不能在2.2.x前改变任 + 何东西。这些条目被数域所排序。 - Krzysztof G.Baranowski - <mailto: kgb@knm.org.pl> - 29 Jul 1998 + Krzysztof G.Baranowski + <mailto: kgb@knm.org.pl> + 29 Jul 1998 -更新魔术表到Linux 2.5.45。刚好越过特性冻结，但是有可能还会有一些新的魔术值在2.6.x之前融入到内核中。 + 更新魔术表到Linux 2.5.45。刚好越过特性冻结，但是有可能还会有一些新的魔 + 术值在2.6.x之前融入到内核中。 - Petr Baudis - <pasky@ucw.cz> - 03 Nov 2002 + Petr Baudis + <pasky@ucw.cz> + 03 Nov 2002 -更新魔术表到Linux 2.5.74。 + 更新魔术表到Linux 2.5.74。 - Fabian Frederick - <ffrederick@users.sourceforge.net> - 09 Jul 2003 + Fabian Frederick + <ffrederick@users.sourceforge.net> + 09 Jul 2003 ===================== ================ ======================== ========================================== 魔术数名 数字 结构 文件 ===================== ================ ======================== ========================================== PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` -CMAGIC 0x0111 user ``include/linux/a.out.h`` -MKISS_DRIVER_MAGIC 0x04bf mkiss_channel ``drivers/net/mkiss.h`` -HDLC_MAGIC 0x239e n_hdlc ``drivers/char/n_hdlc.c`` APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` -CYCLADES_MAGIC 0x4359 cyclades_port ``include/linux/cyclades.h`` -DB_MAGIC 0x4442 fc_info ``drivers/net/iph5526_novram.c`` -DL_MAGIC 0x444d fc_info ``drivers/net/iph5526_novram.c`` FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` -FF_MAGIC 0x4646 fc_info ``drivers/net/iph5526_novram.c`` -ISICOM_MAGIC 0x4d54 isi_port ``include/linux/isicom.h`` -PTY_MAGIC 0x5001 ``drivers/char/pty.c`` -PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.h`` -SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` -STRIP_MAGIC 0x5303 strip ``drivers/net/strip.c`` -X25_ASY_MAGIC 0x5303 x25_asy ``drivers/net/x25_asy.h`` -SIXPACK_MAGIC 0x5304 sixpack ``drivers/net/hamradio/6pack.h`` -AX25_MAGIC 0x5316 ax_disp ``drivers/net/mkiss.h`` -TTY_MAGIC 0x5401 tty_struct ``include/linux/tty.h`` -MGSL_MAGIC 0x5401 mgsl_info ``drivers/char/synclink.c`` -TTY_DRIVER_MAGIC 0x5402 tty_driver ``include/linux/tty_driver.h`` -MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` -TTY_LDISC_MAGIC 0x5403 tty_ldisc ``include/linux/tty_ldisc.h`` -USB_SERIAL_MAGIC 0x6702 usb_serial ``drivers/usb/serial/usb-serial.h`` -FULL_DUPLEX_MAGIC 0x6969 ``drivers/net/ethernet/dec/tulip/de2104x.c`` -USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth ``drivers/usb/class/bluetty.c`` -RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/rfcomm/tty.c`` -USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` -CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` -RPORT_MAGIC 0x00525001 r_port ``drivers/char/rocket_int.h`` -LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` -GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str ``drivers/scsi/gdth_ioctl.h`` -RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` -NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` -RED_MAGIC2 0x170fc2a5 (any) ``mm/slab.c`` BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` -ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data ``drivers/isdn/isdn_x25iface.h`` -ECP_MAGIC 0x21504345 cdkecpsig ``include/linux/cdk.h`` -LSOMAGIC 0x27091997 lso ``drivers/fc4/fc.c`` -LSMAGIC 0x2a3b4d2a ls ``drivers/fc4/fc.c`` -WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} ``include/linux/wanpipe.h`` -CS_CARD_MAGIC 0x43525553 cs_card ``sound/oss/cs46xx.c`` -LABELCL_MAGIC 0x4857434c labelcl_info_s ``include/asm/ia64/sn/labelcl.h`` -ISDN_ASYNC_MAGIC 0x49344C01 modem_info ``include/linux/isdn.h`` -CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info ``drivers/s390/net/ctctty.c`` -ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s ``drivers/isdn/i4l/isdn_net_lib.h`` -SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg ``arch/*/amiga/config.c`` -CS_STATE_MAGIC 0x4c4f4749 cs_state ``sound/oss/cs46xx.c`` -SLAB_C_MAGIC 0x4f17a36d kmem_cache ``mm/slab.c`` -COW_MAGIC 0x4f4f4f4d cow_header_v1 ``arch/um/drivers/ubd_user.c`` -I810_CARD_MAGIC 0x5072696E i810_card ``sound/oss/i810_audio.c`` -TRIDENT_CARD_MAGIC 0x5072696E trident_card ``sound/oss/trident.c`` -ROUTER_MAGIC 0x524d4157 wan_device [in ``wanrouter.h`` pre 3.9] -SAVEKMSG_MAGIC1 0x53415645 savekmsg ``arch/*/amiga/config.c`` -GDA_MAGIC 0x58464552 gda ``arch/mips/include/asm/sn/gda.h`` -RED_MAGIC1 0x5a2cf071 (any) ``mm/slab.c`` -EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev ``drivers/atm/lanai.c`` HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` -PCXX_MAGIC 0x5c6df104 channel ``drivers/char/pcxx.h`` KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` -I810_STATE_MAGIC 0x63657373 i810_state ``sound/oss/i810_audio.c`` -TRIDENT_STATE_MAGIC 0x63657373 trient_state ``sound/oss/trident.c`` -M3_CARD_MAGIC 0x646e6f50 m3_card ``sound/oss/maestro3.c`` -FW_HEADER_MAGIC 0x65726F66 fw_header ``drivers/atm/fore200e.h`` -SLOT_MAGIC 0x67267321 slot ``drivers/hotplug/cpqphp.h`` -SLOT_MAGIC 0x67267322 slot ``drivers/hotplug/acpiphp.h`` -LO_MAGIC 0x68797548 nbd_device ``include/linux/nbd.h`` -OPROFILE_MAGIC 0x6f70726f super_block ``drivers/oprofile/oprofilefs.h`` -M3_STATE_MAGIC 0x734d724d m3_state ``sound/oss/maestro3.c`` -VMALLOC_MAGIC 0x87654320 snd_alloc_track ``sound/core/memory.c`` -KMALLOC_MAGIC 0x87654321 snd_alloc_track ``sound/core/memory.c`` -PWC_MAGIC 0x89DC10AB pwc_device ``drivers/usb/media/pwc.h`` -NBD_REPLY_MAGIC 0x96744668 nbd_reply ``include/linux/nbd.h`` -ENI155_MAGIC 0xa54b872d midway_eprom ``drivers/atm/eni.h`` CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` -DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram ``drivers/scsi/gdth.h`` YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` -HTB_CMAGIC 0xFEFAFEF1 htb_class ``net/sched/sch_htb.c`` NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` ===================== ================ ======================== ========================================== - - -请注意，在声音记忆管理中仍然有一些特殊的为每个驱动定义的魔术值。查看include/sound/sndmagic.h来获取他们完整的列表信息。很多OSS声音驱动拥有自己从声卡PCI ID构建的魔术值-他们也没有被列在这里。 - -IrDA子系统也使用了大量的自己的魔术值，查看include/net/irda/irda.h来获取他们完整的信息。 - -HFS是另外一个比较大的使用魔术值的文件系统-你可以在fs/hfs/hfs.h中找到他们。 diff --git a/Documentation/translations/zh_CN/process/maintainer-pgp-guide.rst b/Documentation/translations/zh_CN/process/maintainer-pgp-guide.rst new file mode 100644 index 000000000000..eb12694a4c59 --- /dev/null +++ b/Documentation/translations/zh_CN/process/maintainer-pgp-guide.rst @@ -0,0 +1,789 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/process/maintainer-pgp-guide.rst + +:翻译: + + 司延腾 Yanteng Si <siyanteng@loongson.cn> + +:校译: + + +=================== +内核维护者 PGP 指南 +=================== + +:作者: Konstantin Ryabitsev <konstantin@linuxfoundation.org> + +本文档面向 Linux 内核开发者，特别是子系统维护人员。文档中含有Linux 基金 +会发布的更通用的 `保护代码完整性`_ 指南中讨论的内容子集。阅读该文档，以更 +深入地讨论本指南中提到的一些主题。 + +.. _`保护代码完整性`: https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md + +PGP 在 Linux 内核开发中的作用 +============================= + +PGP 有助于确保 Linux 内核开发社区产出代码的完整性，并在较小程度上，通过 +PGP 签名的电子邮件交换，在开发者之间建立可信的交流渠道。 + +Linux 内核源代码主要有两种（维护）方式: + +- 分布式源仓库 (git) +- 定期发布快照 (tarballs) + +git 仓库和 tarball 都带有创建官方内核版本的内核开发者的 PGP 签名。这 +些签名提供了加密保证，即保证 kernel.org 或任何其他镜像提供的可下载版本 +与这些开发者在其工作站上的版本相同。为此: + +- git 仓库在所有标签上提供 PGP 签名 +- tarball 为所有下载提供独立的 PGP 签名 + +信任开发者，不要信基础设施 +-------------------------- + +自从 2011 年 kernel.org 核心系统遭到入侵以来，内核存档项目的主要运行原 +则就是假定基础设施的任何部分都可能随时受到入侵。因此，管理员特意采取措施， +强调必须始终信任开发者，不能信任代码托管基础设施，无论后者的安全实践有多好。 + +上述指导原则正是需要本指南的原因。希望确保通过对开发者的信任，我们不会简 +单地将未来潜在安全事件的责任归咎于其他人。目的是提供一套指导开发者可以用 +来创建安全的工作环境并保护用于建立 Linux 内核本身完整性的 PGP 密钥。 + +PGP 工具 +======== + +使用 GnuPG 2.2 或更高版本 +------------------------- + +默认情况下，你的发行版应该已经安装了 GnuPG，你只需要验证你使用的是相当新的 +版本即可。要检查，请运行:: + + $ gpg --version | head -n1 + +如果你有 2.2 或更高版本，那么你就可以开始了。如果你的版本早于 2.2，则本指 +南中的某些命令可能不起作用。 + +配置 gpg-agent 选项 +~~~~~~~~~~~~~~~~~~~ + +GnuPG agent是一个辅助工具，每当你使用该命令时，它都会自动启动gpg，并在 +后台运行，目的是缓存私钥密码。你应该知道两个选项，以便调整密码何时从缓存 +过期: + +- ``default-cache-ttl`` (秒): 如果在生命周期结束之前再次使用相同的 + 密钥，倒计时将重置为另一段时间。默认值为 600（10 分钟）。 +- ``max-cache-ttl`` (秒): 无论你自输入初始密码以来多久使用过密钥， + 如果最大生存时间倒计时结束，你都必须再次输入密码。默认值为 30 分钟。 + +如果你发现这些默认值太短（或太长），你可以编辑 ``~/.gnupg/gpg-agent.conf`` +文件以设置你自己的值:: + + # 常规ttl设置为30分钟，最大ttl设置为2小时 + default-cache-ttl 1800 + max-cache-ttl 7200 + +.. note:: + + 不需要在 shell 会话开始时手动启动 gpg-agent。你可能需要检查 + rc 文件来删除旧版本 GnuPG 中的所有内容，因为它可能不再做正确 + 的事情。 + +保护你的 PGP 密钥 +================= + +本指南假定你已经拥有用于 Linux 内核开发目的的 PGP 密钥。如果你还没 +有，请参阅前面提到的 "`保护代码完整性`_" 文档，以获取有关如何创建新 +密钥的指导。 + +如果你当前的密钥低于 2048 位 (RSA)，你还应该创建一个新密钥。 + +了解 PGP 子密钥 +--------------- + +PGP 密钥很少由单个密钥对组成 - 通常它是独立子密钥的集合，这些子密钥 +可根据其功能用于不同的目的，并在创建时分配。PGP 定义了密钥可以具有的 +四种功能: + +- **[S]** 密钥可用于签名 +- **[E]** 密钥可用于加密 +- **[A]** 密钥可用于身份验证 +- **[C]** 密钥可用于验证其他密钥 + +具有 **[C]** 功能的密钥通常称为“主”密钥，但该术语具有误导性，因为 +它意味着可以使用Certify密钥来代替同一链上的任何其他子密钥（如物理 +“主密钥”可用于打开为其他钥匙制作的锁）。由于情况并非如此，本指南将 +其称为“认证密钥”以避免任何歧义。 + +充分理解以下内容至关重要: + +1. 所有子项彼此完全独立。如果你丢失了私有子密钥，则无法从链上的任何 + 其他私钥恢复或重新创建它。 +2. 除 Certify 密钥外，可以有多个具有相同功能的子密钥（例如，你可 + 以有 2 个有效的加密子密钥、3 个有效的签名子密钥，但只有 1 个有 + 效的认证子密钥）。所有子密钥都是完全独立的——加密到一个 **[E]** + 子密钥的信息（messages）无法使用你可能拥有的任何其他 **[E]** + 子密钥解密。 +3. 单个子密钥可能具有多种功能（例如，你的 **[C]** 密钥也可以是你 + 的 **[S]** 密钥）。 + +携带 **[C]** （证明）能力的密钥是唯一可以用来指示与其他密钥的关系 +的密钥。仅 **[C]** 密钥可用于: + +- 添加或撤销具有 S/E/A 功能的其他密钥（子密钥） +- 添加、更改或撤销与密钥关联的身份 (uid) +- 添加或更改其本身或任何子密钥的到期日期 +- 出于信任网络的目的签署其他人的密钥 + +默认情况下，GnuPG 在生成新密钥时创建以下内容: + +- 一个子密钥同时具有认证和签名功能 (**[SC]**) +- 具有加密功能的单独子密钥 (**[E]**) + +如果你在生成密钥时使用了默认参数，那么这就是你将得到的。你可以通过 +运行命令来验证，例如： ``gpg --list-secret-keys`` + +:: + + sec ed25519 2022-12-20 [SC] [expires: 2024-12-19] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev <adev@kernel.org> + ssb cv25519 2022-12-20 [E] [expires: 2024-12-19] + +在 ``sec`` 这行下面长长的一行就是你的密钥指纹-无论在下文任何地方 +看到 ``[fpr]`` 都指的是这40个字符。 + +确保你的密码强度高 +------------------ + +GnuPG 在将私钥存储到磁盘之前使用密码对其进行加密。这样，即使你的 +``.gnupg`` 目录全部泄露或被盗，攻击者在没有事先获取密码来解密的 +情况下也无法使用你的私钥。 + +你的私钥受到强密码保护是绝对必要的。要设置或更改它，请使用:: + + $ gpg --change-passphrase [fpr] + +创建一个单独的签名子密钥 +------------------------ + +我们的目的是通过将你的证书密钥移动到离线媒介来保护它，因此如果你只 +有组合的 **[SC]** 密钥，那么你应该创建一个单独的签名子密钥:: + + $ gpg --quick-addkey [fpr] ed25519 sign + +.. note:: GnuPG 中的 ECC 支持 + + 请注意，如果你打算使用不支持 ED25519 ECC 密钥的硬件密钥，则 + 应选择“nistp256”或“ed25519”。请参阅下面有关推荐硬件设备的 + 部分。 + + +备份你的证书密钥以进行灾难恢复 +------------------------------ + +你的 PGP 密钥上来自其他开发者的签名越多，出于灾难恢复的原因，你就越 +有理由创建一个位于数字媒体之外的备份版本。 + +创建私钥的可打印硬拷贝的最佳方法是使用 ``paperkey`` 为此目的编写 +的软件。有关输出格式及其相对于其他解决方案的优势的更多详细信息，请参 +阅 ``paperkey`` 参考资料。大多数发行版都应该已经打包了 Paperkey。 + +运行以下命令来创建私钥的硬拷贝备份:: + + $ gpg --export-secret-key [fpr] | paperkey -o /tmp/key-backup.txt + +打印出该文件（或将输出直接传输到 lpr），然后用笔在纸的边缘写下你的密 +码。 **强烈建议这样做**，因为密钥打印输出仍然使用该密码进行加密，并且 +如果你更改了它，你将不记得创建备份时它曾经是什么 - *保证*。 + +将生成的打印输出和手写密码放入信封中，并存放在安全且受到良好保护的地 +方，最好远离你的家，例如银行保险柜。 + +.. note:: + + 你的打印机可能不再是连接到并行端口的简单哑设备，但由于输出仍然使 + 用你的密码进行加密，因此即使“云端打印”的现代打印机也应该保持相 + 对安全的操作 + +备份整个 GnuPG 目录 +------------------- + +.. warning:: + + **!!!不要跳过这个步骤!!!** + +如果你需要恢复 PGP 密钥，拥有一个随时可用的备份非常重要。这与我们 +所做的灾难级准备不同 ``paperkey`` 。每当你需要使用你的证书密钥时， +例如在会议和峰会后更改你自己的密钥或签署其他人的密钥时，你还将依赖 +这些外部副本。 + +首先获取一个小型 USB “拇指” 驱动器（最好是两个！），用于备份目的。 +你需要使用 LUKS 对其进行加密——请参阅你的发行版文档以了解如何完成 +此操作。 + +对于加密密码，你可以使用与 PGP 密钥相同的密码。 + +加密过程完成后，重新插入 USB 驱动器并确保其正确安装。将整个 ``.gnupg`` +目录复制到加密存储:: + + $ cp -a ~/.gnupg /media/disk/foo/gnupg-backup + +你现在应该测试一下，确保一切依然能正常工作:: + + $ gpg --homedir=/media/disk/foo/gnupg-backup --list-key [fpr] + +如果没有出现任何错误，那么就可以开始了。卸下 USB 驱动器，给它贴上 +明显的标签，这样下次需要使用随机 USB 驱动器时就不会把它吹走，然后 +放在安全的地方 - 但不要太远，因为你每次都需要使用它时不时地用于诸 +如编辑身份、添加或撤销子密钥或签署其他人的密钥之类的事情。 + +从你的 homedir 中删除 Certify 密钥 +---------------------------------- + +我们的主目录中的文件并没有我们想象的那么受到保护。它们可以通过多种 +不同的方式泄露或被盗: + +- 在制作快速主目录备份以设置新工作站时意外发生 +- 系统管理员的疏忽或恶意 +- 通过不安全的备份 +- 通过桌面应用程序（浏览器、pdf 查看器等）中的恶意软件 +- 跨越国界时通过胁迫 + +使用良好的密码短语保护你的密钥极大地有助于降低上述任何风险，但密码 +短语可以通过键盘记录器、肩窥或任何其他方式发现。因此，建议的设置是 +从主目录中删除你的证书密钥并将其存储在离线存储中。 + +.. warning:: + + 请参阅上一节并确保你已完整备份 GnuPG 目录。如果你没有可用的 + 备份，我们要做的事情将使你的密钥毫无用处！ + +首先，确定你的证书密钥的keygrip:: + + $ gpg --with-keygrip --list-key [fpr] + +输出将是这样的:: + + pub ed25519 2022-12-20 [SC] [expires: 2022-12-19] + 000000000000000000000000AAAABBBBCCCCDDDD + Keygrip = 1111000000000000000000000000000000000000 + uid [ultimate] Alice Dev <adev@kernel.org> + sub cv25519 2022-12-20 [E] [expires: 2022-12-19] + Keygrip = 2222000000000000000000000000000000000000 + sub ed25519 2022-12-20 [S] + Keygrip = 3333000000000000000000000000000000000000 + +找到该线 ``pub`` 下方的keygrip项 （位于“认证密钥指纹”的正下方）。 +这将直接对应于你``~/.gnupg`` 目录中的一个文件:: + + $ cd ~/.gnupg/private-keys-v1.d + $ ls + 1111000000000000000000000000000000000000.key + 2222000000000000000000000000000000000000.key + 3333000000000000000000000000000000000000.key + +你所要做的只是删除与证书密钥 keygrip 对应的 .key 文件:: + + $ cd ~/.gnupg/private-keys-v1.d + $ rm 1111000000000000000000000000000000000000.key + +现在，如果你发出命令 ``--list-secret-keys`` ，它将显示证书密钥丢 +失（ 表示 ``#`` 它不可用）:: + + $ gpg --list-secret-keys + sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev <adev@kernel.org> + ssb cv25519 2022-12-20 [E] [expires: 2024-12-19] + ssb ed25519 2022-12-20 [S] + +你还应该删除 ``~/.gnupg``目录中的所有 ``secring.gpg`` 文件 ，这些 +文件可能是以前版本的 GnuPG 留下的。 + +如果你没有“private-keys-v1.d”目录 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +如果你没有 ``~/.gnupg/private-keys-v1.d`` 目录，那么你的密钥仍存 +储在 GnuPG v1 使用的旧文件 ``secring.gpg`` 中。对密钥进行任何更改 +（例如更改密码或添加子密钥）应该会自动转换旧 ``secring.gpg`` 格式以 +供使用 ``private-keys-v1.d`` 。 + +完成此操作后，请确保删除过时的 ``secring.gpg`` 文件，其中仍然包含你 +的私钥。 + + +将子密钥移至专用加密设备 +======================== + +尽管 Certify 密钥现在不会被泄露或被盗，但子密钥仍然位于你的主目录中。 +任何设法获得这些内容的人都将能够解密你的通信或伪造你的签名（如果他们知 +道密码）。此外，每次执行 GnuPG 操作时，密钥都会加载到系统内存中，并 +可能被足够高级的恶意软件（例如 Meltdown 和 Spectre）从那里窃取。 + +完全保护密钥的最佳方法是将它们转移到能够进行智能卡操作的专用硬件设备上。 + +智能卡的好处 +------------ + +智能卡包含一个加密芯片，能够存储私钥并直接在卡本身上执行加密操作。由于 +密钥内容永远不会离开智能卡，因此插入硬件设备的计算机的操作系统无法自行 +检索私钥。这与我们之前用于备份目的的加密 USB 存储设备有很大不同——当 +USB 设备插入并安装时，操作系统能够访问私钥内容。 + +使用外部加密 USB 介质并不能替代具有智能卡功能的设备。 + +可用的智能卡设备 +---------------- + +除非你的所有笔记本电脑和工作站都有智能卡读卡器，否则最简单的方法是获 +取实现智能卡功能的专用 USB 设备。有多种选择：: + +- `Nitrokey Start`_: 开放硬件和免费软件，日本基于FSI的 `Gnuk` 。 + 少数支持 ED25519 ECC 密钥的商用设备之一，但提供的安全功能最少 + （例如防篡改或某些旁路攻击）。 +- `Nitrokey Pro 2`_: 与 Nitrokey Start 类似，但更防篡改并提供 + 更多安全功能。Pro 2 支持 ECC 加密 (NISTP)。 +- `Yubikey 5`_: 专有硬件和软件，但比 Nitrokey Pro 便宜，并且以 + USB-C 形式提供，对于较新的笔记本电脑更有用。提供额外的安全功能， + 例如 FIDO U2F 等，现在终于支持 NISTP 和 ED25519 ECC 密钥。 + +你的选择将取决于成本、你所在地理区域的货运便利性以及开放/专有硬件考虑 +因素。 + +.. note:: + + 如果你位列于 MAINTAINERS 中或在 kernel.org 上拥有帐户，则你有 + 资格获得Linux 基金会提供的_`qualify for a free Nitrokey Start` 。 + +.. _`Nitrokey Start`: https://shop.nitrokey.com/shop/product/nitrokey-start-6 +.. _`Nitrokey Pro 2`: https://shop.nitrokey.com/shop/product/nkpr2-nitrokey-pro-2-3 +.. _`Yubikey 5`: https://www.yubico.com/products/yubikey-5-overview/ +.. _Gnuk: https://www.fsij.org/doc-gnuk/ +.. _`qualify for a free Nitrokey Start`: https://www.kernel.org/nitrokey-digital-tokens-for-kernel-developers.html + +配置你的智能卡设备 +------------------ + +当你将智能卡设备插入任何现代 Linux 工作站时，它就应该可以正常工作 +(TM)。你可以通过运行来验证它:: + + $ gpg --card-status + +如果你看到完整的智能卡详细信息，那么你就可以开始了。不幸的是，对所有 +可能无法正常工作的原因进行故障排除超出了本指南的范围。如果你在使该卡 +与 GnuPG 配合使用时遇到问题，请通过常规支持渠道寻求帮助。 + +要配置你的智能卡，你需要使用 GnuPG 菜单系统，因为没有方便的命令行开 +关:: + + $ gpg --card-edit + [...omitted...] + gpg/card> admin + Admin commands are allowed + gpg/card> passwd + +你应该设置用户 PIN (1)、管理员 PIN (3) 和重置代码 (4)。请确保将 +这些信息记录并存储在安全的地方，尤其是管理员 PIN 码和重置代码（它允 +许你完全擦除智能卡）。你很少需要使用管理员 PIN 码，如果你不记录它， +你将不可避免地忘记它是什么。 + +回到主卡菜单，你还可以设置其他值（例如姓名、性别、登录数据等），但这 +不是必需的，并且如果你丢失智能卡，还会泄露有关智能卡的信息。 + +.. note:: + + 尽管名称为“PIN”，但卡上的用户 PIN 和管理员 PIN 都不需要是数字。 + +.. warning:: + + 某些设备可能要求你将子密钥移至设备上，然后才能更改密码。请检查设 + 备制造商提供的文档。 + +将子密钥移至你的智能卡 +---------------------- + +退出卡菜单（使用“q”）并保存所有更改。接下来，让我们将子密钥移至智能卡 +上。对于大多数操作，你将需要 PGP 密钥密码和卡的管理员 PIN:: + + $ gpg --edit-key [fpr] + + Secret subkeys are available. + + pub ed25519/AAAABBBBCCCCDDDD + created: 2022-12-20 expires: 2024-12-19 usage: SC + trust: ultimate validity: ultimate + ssb cv25519/1111222233334444 + created: 2022-12-20 expires: never usage: E + ssb ed25519/5555666677778888 + created: 2017-12-07 expires: never usage: S + [ultimate] (1). Alice Dev <adev@kernel.org> + + gpg> + +使用 ``--edit-key`` 使我们再次进入菜单模式，你会注意到按键列表有点 +不同。从现在开始，所有命令都在此菜单模式内完成，如 所示 ``gpg>``。 + +首先，让我们选择要放入卡上的密钥 - 你可以通过键入 ``key 1`` （它是 +列表中的第一个， **[E]** 子密钥）来完成此操作： + + gpg> key 1 + +在输出中，你现在在 **[E]** 子密钥应该看到 ``ssb*`` 。意味着这个子 +密钥当前被选中。它用作切换键，这意味着如果你再次输入 ``key 1`` ， +``*`` 将会消失并且该键将不再被选择。 + +现在，让我们将该密钥移至智能卡上:: + + gpg> keytocard + Please select where to store the key: + (2) Encryption key + Your selection? 2 + +由于它是我们的 **[E]** 密钥，因此将其放入加密槽中是有意义的。当你提 +交选择时，系统将首先提示你输入 PGP 密钥密码，然后输入管理员 PIN 码。 +如果命令返回且没有错误，则你的密钥已被移动。 + +**重要提示**：现在再次键入 ``key 1`` 以取消选择第一个键，并 ``key 2`` +选择 **[S]** 密钥:: + + gpg> key 1 + gpg> key 2 + gpg> keytocard + Please select where to store the key: + (1) Signature key + (3) Authentication key + Your selection? 1 + +你可以使用 **[S]** 密钥进行签名和身份验证，但我们希望确保它位于签名槽中， +因此选择 (1)。跟之前一样，如果你的命令返回且没有错误，则操作成功:: + + gpg> q + Save changes? (y/N) y + +保存更改将删除你从主目录移动到卡上的密钥（但这没关系，因为我们还有备份， +让我们需要替换智能卡时再次执行此操作）。 + +验证密钥是否已移动 +~~~~~~~~~~~~~~~~~~ + +如果你现在执行 ``--list-secret-keys`` ，你将看到输出中存在细微的差异:: + + $ gpg --list-secret-keys + sec# ed25519 2022-12-20 [SC] [expires: 2024-12-19] + 000000000000000000000000AAAABBBBCCCCDDDD + uid [ultimate] Alice Dev <adev@kernel.org> + ssb> cv25519 2022-12-20 [E] [expires: 2024-12-19] + ssb> ed25519 2022-12-20 [S] + +在 ``ssb>``中的 ``>`` 输出意味着子密钥只能在智能卡上可用，如果你返回 +密钥目录并查看那里的内容，你会注意到 ``.key`` 那里的文件已被存根替换:: + + $ cd ~/.gnupg/private-keys-v1.d + $ strings *.key | grep 'private-key' + +输出应包含 ``shadowed-private-key`` 指示这些文件只是存根，实际内容 +位于智能卡上。 + +验证智能卡是否正常工作 +~~~~~~~~~~~~~~~~~~~~~~ + +要验证智能卡是否按预期工作，你可以创建签名:: + + $ echo "Hello world" | gpg --clearsign > /tmp/test.asc + $ gpg --verify /tmp/test.asc + +在你的第一条命令执行时，应该会询问你智能卡的PIN，然后在你运行 +``gpg --verify`` 后显示"Good signature"。 + +恭喜，你已成功使窃取你的数字开发者身份变得极其困难！ + +其他常见的 GnuPG 操作 +--------------------- + +以下是你需要使用 PGP 密钥执行的一些常见操作的快速参考。 + +安装你的安全离线存储 +~~~~~~~~~~~~~~~~~~~~ + +你将需要你的证书密钥来执行以下任何操作，因此你首先需要安装备份离线存储 +并告诉 GnuPG 使用它:: + + $ export GNUPGHOME=/media/disk/foo/gnupg-backup + $ gpg --list-secret-keys + +你需要确保你看到 ``sec`` 而不是 ``sec#`` 在输出中（ ``#`` 意味着 +密钥不可用并且你仍在使用常规主目录位置）。 + +延长密钥有效期 +~~~~~~~~~~~~~~ + +证书密钥的默认到期日期为自创建之日起 2 年。这样做既是出于安全原因，也 +是为了使过时的密钥最终从密钥服务器中消失。 + +要将密钥的有效期从当前日期延长一年，只需运行:: + + $ gpg --quick-set-expire [fpr] 1y + +如果更容易记住，你也可以使用特定日期（例如你的生日、1 月 1 日或加拿大 +国庆日）:: + + $ gpg --quick-set-expire [fpr] 2025-07-01 + +请记住将更新后的密钥发送回密钥服务器:: + + $ gpg --send-key [fpr] + +进行任何更改后更新你的工作目录 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +使用离线存储对密钥进行任何更改后，你需要将这些更改导入回常规工作目录 +中:: + + $ gpg --export | gpg --homedir ~/.gnupg --import + $ unset GNUPGHOME + +通过 ssh 使用 gpg-agent +~~~~~~~~~~~~~~~~~~~~~~~ + +如果你需要在远程系统上签署标签或提交，你可以通过 ssh 转发你的 +gpg-agent。 + +请参考 GnuPG wiki 上提供的说明: + +- `Agent通过SSH转发`_ + +如果你可以修改远程端的 sshd 服务器设置，则工作会更顺利。 + +.. _`Agent通过SSH转发`: https://wiki.gnupg.org/AgentForwarding + +将 PGP 与 Git 结合使用 +====================== + +Git 的核心功能之一是它的分散性——一旦将仓库克隆到你的系统，你就拥有该 +项目的完整历史记录，包括其所有标签、提交和分支。然而，随着数百个克隆仓 +库的出现，人们如何验证他们的 linux.git 副本没有被恶意第三方篡改？ + +或者，如果在代码中发现后门，并且提交中的“Author”行表示它是由你完成的， +而你非常确定 `自己与它无关`_ ，会发生什么？ + +为了解决这两个问题，Git 引入了 PGP 集成。签名的标签通过确保其内容与创 +建标签的开发人员的工作站上的内容完全相同来证明仓库的完整性，而签名的提 +交使其他人几乎不可能在无法访问你的 PGP 密钥的情况下冒充你。 + +.. _`自己与它无关`: https://github.com/jayphelps/git-blame-someone-else + +配置 git 使用你的 PGP 密钥 +-------------------------- + +如果你的密钥环中只有一个密钥，那么你实际上不需要执行任何额外操作，因为 +它会成为你的默认密钥。但是，如果你碰巧有多个密钥，你可以告诉 git 应该 +使用哪个密钥（``[fpr]`` 是你密钥的指纹）:: + + $ git config --global user.signingKey [fpr] + +如何使用签名标签 +---------------- + +要创建签名标签，只需将 ``-s`` 开关传递给 tag 命令:: + + $ git tag -s [tagname] + +我们的建议是始终签署 git 标签，因为这可以让其他开发人员确保他们从中提 +取的 git 仓库没有被恶意更改。 + +如何验证签名标签 +~~~~~~~~~~~~~~~~ + +要验证签名标签，只需使用以下 ``verify-tag`` 命令:: + + $ git verify-tag [tagname] + +如果你从项目仓库的另一个分支中拉取标签，git 应该自动验证你拉取的顶 +部的签名，并在合并操作期间向你显示结果:: + + $ git pull [url] tags/sometag + +合并消息将包含如下内容:: + + Merge tag 'sometag' of [url] + + [Tag message] + + # gpg: Signature made [...] + # gpg: Good signature from [...] + +如果你正在验证其他人的 git 标签，那么你将需要导入他们的 PGP 密钥。 +请参阅下面的":ref:`身份验证`"部分。 + +配置 git 始终对带注释的标签（annotated tags）进行签名annotated tags +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +如果你要创建带注释的标签，你很可能会想要对其进行签名。要强制 git 始终签 +署带注释的标签，你可以设置一个全局配置选项:: + + $ git config --global tag.forceSignAnnotated true + +如何使用签名的提交 +------------------ + +创建签名提交很容易，但在 Linux 内核开发中使用它们要困难得多，因为它依赖 +于发送到邮件列表的补丁，并且此工作流程不保留 PGP 提交签名。此外，当重新 +调整仓库以匹配上游时，甚至你自己的 PGP 提交签名最终也会被丢弃。因此，大 +多数内核开发人员不会费心签署他们的提交，并且会忽略他们在工作中依赖的任何 +外部仓库中的签名提交。 + +但是，如果你的工作 git 树在某些 git 托管服务（kernel.org、 +infradead.org、ozlabs.org 或其他）上公开可用，那么建议你签署所有 git +提交，即使上游开发人员不直接受益于这种做法。 + +我们推荐这样做的原因如下: + +1. 如果需要执行代码取证或跟踪代码来源，即使是外部维护的带有 PGP 提交签名 + 的树对于此类问题也很有价值。 +2. 如果你需要重新克隆本地仓库（例如，在磁盘故障后），这可以让你在恢复工 + 作之前轻松验证仓库的完整性。 +3. 如果有人需要挑选你的提交，这可以让他们在应用之前快速验证其完整性。 + +创建签名提交 +~~~~~~~~~~~~ + +要创建签名提交，你只需将 ``-S`` 标志传递给 ``git commit`` 命令（由于 +与另一个标志冲突，所以它是大写的 ``-S`` ）:: + + $ git commit -S + +配置 git 始终对提交进行签名 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +你可以告诉 git 总是签署提交:: + + git config --global commit.gpgSign true + +.. note:: + + 确保 ``gpg-agent`` 在打开此功能之前进行配置。 + +.. _身份验证: + + +如何使用签名补丁 +---------------- + +可以使用你的 PGP 密钥来签署发送到内核开发人员邮件列表的补丁。由于现有的 +电子邮件签名机制（PGP-Mime 或 PGP-inline）往往会导致常规代码审查任务 +出现问题，因此你应该使用为此创建的 kernel.org 工具，该工具将加密证明签 +名放入消息标头中（a-la DKIM）: + +- `Patatt Patch Attestation`_ + +.. _`Patatt Patch Attestation`: https://pypi.org/project/patatt/ + +安装和配置 patatt +~~~~~~~~~~~~~~~~~ + +Patatt 已针对许多发行版进行了打包，因此请先检查那里。你还可以使用 +“ ``pip install patatt`` ”从 pypi 安装它。 + +如果你已经使用 git 配置了 PGP 密钥（通过``user.signingKey`` 配置参数）， +则 patatt 不需要进一步配置。你可以通过在所需的仓库中安装 git-send-email +钩子来开始签署补丁:: + + patatt install-hook + +现在，你使用 ``git send-email`` 发送的任何补丁都将自动使用你的加密签 +名进行签名 + +检查 patatt 签名 +~~~~~~~~~~~~~~~~ + +如果你用于 ``b4`` 检索和应用补丁，那么它将自动尝试验证它遇到的所有 +DKIM 和 patatt 签名，例如:: + + $ b4 am 20220720205013.890942-1-broonie@kernel.org + [...] + Checking attestation on all messages, may take a moment... + --- + ✓ [PATCH v1 1/3] kselftest/arm64: Correct buffer allocation for SVE Z registers + ✓ [PATCH v1 2/3] arm64/sve: Document our actual ABI for clearing registers on syscall + ✓ [PATCH v1 3/3] kselftest/arm64: Enforce actual ABI for SVE syscalls + --- + ✓ Signed: openpgp/broonie@kernel.org + ✓ Signed: DKIM/kernel.org + +.. note:: + + Patatt 和 b4 仍在积极开发中，你应该检查这些项目的最新文档以了解任 + 何新功能或更新功能。 + +如何验证内核开发者身份 +====================== + +签署标签和提交很容易，但是如何验证用于签署某项内容的密钥是否属于实际的内 +核开发人员而不是恶意冒名顶替者？ + +使用 WKD 和 DANE 配置auto-key-locate（自动密钥检索） +---------------------------------------------------- + +如果你还没有广泛收集其他开发人员的公钥，那么你可以依靠密钥自动发现和自动 +检索来快速启动你的密钥环。如果从头开始创建自己的信任 Web 的预期太令人畏 +惧， GnuPG 可以借助其他委托信任技术（即 DNSSEC 和 TLS）来帮助你继续前 +进。 + +将以下内容添加到你的 ``~/.gnupg/gpg.conf``:: + + auto-key-locate wkd,dane,local + auto-key-retrieve + +基于 DNS 的命名实体身份验证（“DANE”）是一种在 DNS 中发布公钥并使用 +DNSSEC 签名区域保护它们的方法。Web 密钥目录（“WKD”）是使用 https +查找来达到相同目的的替代方法。当使用 DANE 或 WKD 查找公钥时，GnuPG +将分别验证 DNSSEC 或 TLS 证书，然后将自动检索的公钥添加到本地密钥环。 + +Kernel.org 为所有拥有 kernel.org 帐户的开发人员发布 WKD。一旦你的 +``gpg.conf`` 中进行了上述更改，你就可以自动检索 Linus Torvalds 和 +Greg Kroah-Hartman 的密钥（如果你还没有它们）:: + + $ gpg --locate-keys torvalds@kernel.org gregkh@kernel.org + +如果你有 kernel.org 帐户，那么你应该 `添加 kernel.org UID 到你的密钥中`_ +添加到你的密钥中，以使 WKD 对其他内核开发人员更有用。 + +.. _`添加 kernel.org UID 到你的密钥中`: https://korg.wiki.kernel.org/userdoc/mail#adding_a_kernelorg_uid_to_your_pgp_key + +信任网 (WOT) 与首次使用信任 (TOFU) +----------------------------------- + +PGP 结合了称为“信任网”的信任委托机制。从本质上讲，这是一次尝试取代 +HTTPS/TLS 世界对集中式证书颁发机构的需求。PGP 将这一责任留给每个 +用户，而不是由各种软件制造商规定谁应该是你值得信赖的认证实体。 + +不幸的是，很少有人了解信任网是如何运作的。虽然它仍然是 OpenPGP 规 +范的一个重要方面，但最新版本的 GnuPG（2.2 及更高版本）已经实现了 +一种称为“首次使用信任”(TOFU) 的替代机制。你可以将 TOFU 视为“类似 +SSH 的信任方法”。使用 SSH，第一次连接到远程系统时，其密钥指纹会被 +记录并记住。如果将来密钥发生变化，SSH 客户端将向你发出警报并拒绝连 +接，迫使你决定是否选择信任更改后的密钥。同样，第一次导入某人的 PGP +密钥时，它被认为是有效的。如果将来的任何时候 GnuPG 遇到具有相同标 +识的另一个密钥，则先前导入的密钥和新密钥都将被标记为无效，你将需要手 +动确定保留哪一个。 + +我们建议你使用 TOFU+PGP 组合信任模型（这是 GnuPG v2 中新默认的）。 +若要设置它，在 ``~/.gnupg/gpg.conf`` 中添加（或修改） +``trust-model`` 设置:: + + trust-model tofu+pgp + +使用 kernel.org 信任网仓库 +-------------------------- + +Kernel.org 维护着一个包含开发人员公钥的 git 仓库，作为复制密钥服 +务器网络的替代品，而在过去几年中，该网络几乎已经陷入黑暗。有关如何将 +该仓库设置为公钥来源的完整文档可以在此处找到: + +- `内核开发者密钥环`_ + +如果你是内核开发人员，请考虑提交你的密钥以将其包含到该密钥环中。 + +.. _`内核开发者密钥环`: https://korg.docs.kernel.org/pgpkeys.html diff --git a/Documentation/translations/zh_CN/process/management-style.rst b/Documentation/translations/zh_CN/process/management-style.rst index c6a5bb285797..8053ae474328 100644 --- a/Documentation/translations/zh_CN/process/management-style.rst +++ b/Documentation/translations/zh_CN/process/management-style.rst @@ -36,14 +36,14 @@ Linux内核管理风格 每个人都认为管理者做决定，而且决策很重要。决定越大越痛苦，管理者就必须越高级。 这很明显，但事实并非如此。 -游戏的名字是 **避免** 做出决定。尤其是，如果有人告诉你“选择（a）或（b）， +最重要的是 **避免** 做出决定。尤其是，如果有人告诉你“选择（a）或（b）， 我们真的需要你来做决定”，你就是陷入麻烦的管理者。你管理的人比你更了解细节， 所以如果他们来找你做技术决策，你完蛋了。你显然没有能力为他们做这个决定。 （推论：如果你管理的人不比你更了解细节，你也会被搞砸，尽管原因完全不同。 也就是说，你的工作是错的，他们应该管理你的才智） -所以游戏的名字是 **避免** 做出决定，至少是那些大而痛苦的决定。做一些小的 +所以最重要的是 **避免** 做出决定，至少是那些大而痛苦的决定。做一些小的 和非结果性的决定是很好的，并且使您看起来好像知道自己在做什么，所以内核管理者 需要做的是将那些大的和痛苦的决定变成那些没有人真正关心的小事情。 diff --git a/Documentation/translations/zh_CN/process/programming-language.rst b/Documentation/translations/zh_CN/process/programming-language.rst index 2a47a1d2ec20..fabdc338dbfb 100644 --- a/Documentation/translations/zh_CN/process/programming-language.rst +++ b/Documentation/translations/zh_CN/process/programming-language.rst @@ -9,8 +9,7 @@ ============ 内核是用C语言 :ref:`c-language <cn_c-language>` 编写的。更准确地说，内核通常是用 :ref:`gcc <cn_gcc>` -在 ``-std=gnu89`` :ref:`gcc-c-dialect-options <cn_gcc-c-dialect-options>` 下编译的：ISO C90的 GNU 方言（ -包括一些C99特性） +在 ``-std=gnu11`` :ref:`gcc-c-dialect-options <cn_gcc-c-dialect-options>` 下编译的：ISO C11的 GNU 方言 这种方言包含对语言 :ref:`gnu-extensions <cn_gnu-extensions>` 的许多扩展，当然，它们许多都在内核中使用。 diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst index 8738c55e42a2..10536b74aeec 100644 --- a/Documentation/translations/zh_CN/process/submit-checklist.rst +++ b/Documentation/translations/zh_CN/process/submit-checklist.rst @@ -1,107 +1,110 @@ .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/submit-checklist.rst <submitchecklist>` -:Translator: Alex Shi <alex.shi@linux.alibaba.com> +:Original: Documentation/process/submit-checklist.rst +:Translator: + - Alex Shi <alexs@kernel.org> + - Wu XiangCheng <bobwxc@email.cn> .. _cn_submitchecklist: -Linux内核补丁提交清单 -~~~~~~~~~~~~~~~~~~~~~ +Linux内核补丁提交检查单 +~~~~~~~~~~~~~~~~~~~~~~~ 如果开发人员希望看到他们的内核补丁提交更快地被接受，那么他们应该做一些基本 的事情。 -这些都是在 -:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` +这些都是在 Documentation/translations/zh_CN/process/submitting-patches.rst 和其他有关提交Linux内核补丁的文档中提供的。 -1) 如果使用工具，则包括定义/声明该工具的文件。不要依赖于其他头文件拉入您使用 +1) 如果使用工具，则包括定义/声明该工具的文件。不要依赖其他头文件来引入您使用 的头文件。 2) 干净的编译： - a) 使用适用或修改的 ``CONFIG`` 选项 ``=y``、``=m`` 和 ``=n`` 。没有GCC + a) 使用合适的 ``CONFIG`` 选项 ``=y``、``=m`` 和 ``=n`` 。没有 ``gcc`` 警告/错误，没有链接器警告/错误。 - b) 通过allnoconfig、allmodconfig + b) 通过 ``allnoconfig`` 、 ``allmodconfig`` c) 使用 ``O=builddir`` 时可以成功编译 -3) 通过使用本地交叉编译工具或其他一些构建场在多个CPU体系结构上构建。 + d) 任何 Doucmentation/ 下的变更都能成功构建且不引入新警告/错误。 + 用 ``make htmldocs`` 或 ``make pdfdocs`` 检验构建情况并修复问题。 + +3) 通过使用本地交叉编译工具或其他一些构建设施在多个CPU体系结构上构建。 4) PPC64是一种很好的交叉编译检查体系结构，因为它倾向于对64位的数使用无符号 长整型。 -5) 如下所述 :ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>`. - 检查您的补丁是否为常规样式。在提交（ ``scripts/check patch.pl`` ）之前， - 使用补丁样式检查器检查是否有轻微的冲突。您应该能够处理您的补丁中存在的所有 +5) 按 Documentation/translations/zh_CN/process/coding-style.rst 所述检查您的 + 补丁是否为常规样式。在提交之前使用补丁样式检查器 ``scripts/checkpatch.pl`` + 检查是否有轻微的冲突。您应该能够处理您的补丁中存在的所有 违规行为。 -6) 任何新的或修改过的 ``CONFIG`` 选项都不会弄脏配置菜单，并默认为关闭，除非 - 它们符合 ``Documentation/kbuild/kconfig-language.rst`` 中记录的异常条件, - 菜单属性：默认值. +6) 任何新的或修改过的 ``CONFIG`` 选项都不应搞乱配置菜单，并默认为关闭，除非 + 它们符合 ``Documentation/kbuild/kconfig-language.rst`` 菜单属性：默认值中 + 记录的例外条件。 7) 所有新的 ``kconfig`` 选项都有帮助文本。 8) 已仔细审查了相关的 ``Kconfig`` 组合。这很难用测试来纠正——脑力在这里是有 回报的。 -9) 用 sparse 检查干净。 +9) 通过 sparse 清查。 + （参见 Documentation/translations/zh_CN/dev-tools/sparse.rst ） -10) 使用 ``make checkstack`` 和 ``make namespacecheck`` 并修复他们发现的任何 - 问题。 +10) 使用 ``make checkstack`` 并修复他们发现的任何问题。 .. note:: - ``checkstack`` 并没有明确指出问题，但是任何一个在堆栈上使用超过512 + ``checkstack`` 并不会明确指出问题，但是任何一个在堆栈上使用超过512 字节的函数都可以进行更改。 -11) 包括 :ref:`kernel-doc <kernel_doc>` 内核文档以记录全局内核API。（静态函数 - 不需要，但也可以。）使用 ``make htmldocs`` 或 ``make pdfdocs`` 检查 - :ref:`kernel-doc <kernel_doc>` 并修复任何问题。 +11) 包括 :ref:`kernel-doc <kernel_doc_zh>` 内核文档以记录全局内核API。（静态 + 函数不需要，但也可以。）使用 ``make htmldocs`` 或 ``make pdfdocs`` 检查 + :ref:`kernel-doc <kernel_doc_zh>` 并修复任何问题。 -12) 通过以下选项同时启用的测试 ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, +12) 通过以下选项同时启用的测试： ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, - ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` - -13) 已经过构建和运行时测试，包括有或没有 ``CONFIG_SMP``, ``CONFIG_PREEMPT``. + ``CONFIG_PROVE_RCU`` 和 ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` 。 -14) 如果补丁程序影响IO/磁盘等：使用或不使用 ``CONFIG_LBDAF`` 进行测试。 +13) 在 ``CONFIG_SMP``, ``CONFIG_PREEMPT`` 开启和关闭的情况下都进行构建和运行 + 时测试。 -15) 所有代码路径都已在启用所有lockdep功能的情况下运行。 +14) 所有代码路径都已在启用所有死锁检测（lockdep）功能的情况下运行。 -16) 所有新的/proc条目都记录在 ``Documentation/`` +15) 所有新的 ``/proc`` 条目都记录在 ``Documentation/`` -17) 所有新的内核引导参数都记录在 +16) 所有新的内核引导参数都记录在 Documentation/admin-guide/kernel-parameters.rst 中。 -18) 所有新的模块参数都记录在 ``MODULE_PARM_DESC()`` +17) 所有新的模块参数都记录在 ``MODULE_PARM_DESC()`` -19) 所有新的用户空间接口都记录在 ``Documentation/ABI/`` 中。有关详细信息， +18) 所有新的用户空间接口都记录在 ``Documentation/ABI/`` 中。有关详细信息， 请参阅 ``Documentation/ABI/README`` 。更改用户空间接口的补丁应该抄送 linux-api@vger.kernel.org。 -20) 检查是否全部通过 ``make headers_check`` 。 - -21) 已通过至少注入slab和page分配失败进行检查。请参阅 ``Documentation/fault-injection/`` +19) 已通过至少注入slab和page分配失败进行检查。请参阅 ``Documentation/fault-injection/`` 。 如果新代码是实质性的，那么添加子系统特定的故障注入可能是合适的。 -22) 新添加的代码已经用 ``gcc -W`` 编译（使用 ``make EXTRA-CFLAGS=-W`` ）。这 +20) 新添加的代码已经用 ``gcc -W`` 编译（使用 ``make EXTRA-CFLAGS=-W`` ）。这 将产生大量噪声，但对于查找诸如“警告：有符号和无符号之间的比较”之类的错误 很有用。 -23) 在它被合并到-mm补丁集中之后进行测试，以确保它仍然与所有其他排队的补丁以 +21) 在它被合并到-mm补丁集中之后进行测试，以确保它仍然与所有其他排队的补丁以 及VM、VFS和其他子系统中的各种更改一起工作。 -24) 所有内存屏障例如 ``barrier()``, ``rmb()``, ``wmb()`` 都需要源代码中的注 +22) 所有内存屏障（例如 ``barrier()``, ``rmb()``, ``wmb()`` ）都需要源代码注 释来解释它们正在执行的操作及其原因的逻辑。 -25) 如果补丁添加了任何ioctl，那么也要更新 ``Documentation/ioctl/ioctl-number.rst`` +23) 如果补丁添加了任何ioctl，那么也要更新 + ``Documentation/userspace-api/ioctl/ioctl-number.rst`` 。 -26) 如果修改后的源代码依赖或使用与以下 ``Kconfig`` 符号相关的任何内核API或 +24) 如果修改后的源代码依赖或使用与以下 ``Kconfig`` 符号相关的任何内核API或 功能，则在禁用相关 ``Kconfig`` 符号和/或 ``=m`` （如果该选项可用）的情况 下测试以下多个构建[并非所有这些都同时存在，只是它们的各种/随机组合]： - ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, - ``CONFIG_NET``, ``CONFIG_INET=n`` (但是后者伴随 ``CONFIG_NET=y``). + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, + ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` （但是最后一个需要 ``CONFIG_NET=y`` ）。 diff --git a/Documentation/translations/zh_CN/process/submitting-drivers.rst b/Documentation/translations/zh_CN/process/submitting-drivers.rst deleted file mode 100644 index d99885c27aed..000000000000 --- a/Documentation/translations/zh_CN/process/submitting-drivers.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. _cn_submittingdrivers: - -.. include:: ../disclaimer-zh_CN.rst - -:Original: :ref:`Documentation/process/submitting-drivers.rst - <submittingdrivers>` - -如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 -交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 -译存在问题，请联系中文版维护者:: - - 中文版维护者： 李阳 Li Yang <leoyang.li@nxp.com> - 中文版翻译者： 李阳 Li Yang <leoyang.li@nxp.com> - 中文版校译者： 陈琦 Maggie Chen <chenqi@beyondsoft.com> - 王聪 Wang Cong <xiyou.wangcong@gmail.com> - 张巍 Zhang Wei <wezhang@outlook.com> - -如何向 Linux 内核提交驱动程序 -============================= - -这篇文档将会解释如何向不同的内核源码树提交设备驱动程序。请注意，如果你感 -兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(http://www.xfree86.org/) -和／或 X.org 项目 (http://x.org)。 - -另请参阅 Documentation/translations/zh_CN/process/submitting-patches.rst 文档。 - - -分配设备号 ----------- - -块设备和字符设备的主设备号与从设备号是由 Linux 命名编号分配权威 LANANA（ -现在是 Torben Mathiasen）负责分配。申请的网址是 http://www.lanana.org/。 -即使不准备提交到主流内核的设备驱动也需要在这里分配设备号。有关详细信息， -请参阅 Documentation/admin-guide/devices.rst。 - -如果你使用的不是已经分配的设备号，那么当你提交设备驱动的时候，它将会被强 -制分配一个新的设备号，即便这个设备号和你之前发给客户的截然不同。 - -设备驱动的提交对象 ------------------- - -Linux 2.0: - 此内核源码树不接受新的驱动程序。 - -Linux 2.2: - 此内核源码树不接受新的驱动程序。 - -Linux 2.4: - 如果所属的代码领域在内核的 MAINTAINERS 文件中列有一个总维护者， - 那么请将驱动程序提交给他。如果此维护者没有回应或者你找不到恰当的 - 维护者，那么请联系 Willy Tarreau <w@1wt.eu>。 - -Linux 2.6: - 除了遵循和 2.4 版内核同样的规则外，你还需要在 linux-kernel 邮件 - 列表上跟踪最新的 API 变化。向 Linux 2.6 内核提交驱动的顶级联系人 - 是 Andrew Morton <akpm@linux-foundation.org>。 - -决定设备驱动能否被接受的条件 ----------------------------- - -许可： 代码必须使用 GNU 通用公开许可证 (GPL) 提交给 Linux，但是 - 我们并不要求 GPL 是唯一的许可。你或许会希望同时使用多种 - 许可证发布，如果希望驱动程序可以被其他开源社区（比如BSD） - 使用。请参考 include/linux/module.h 文件中所列出的可被 - 接受共存的许可。 - -版权： 版权所有者必须同意使用 GPL 许可。最好提交者和版权所有者 - 是相同个人或实体。否则，必需列出授权使用 GPL 的版权所有 - 人或实体，以备验证之需。 - -接口： 如果你的驱动程序使用现成的接口并且和其他同类的驱动程序行 - 为相似，而不是去发明无谓的新接口，那么它将会更容易被接受。 - 如果你需要一个 Linux 和 NT 的通用驱动接口，那么请在用 - 户空间实现它。 - -代码： 请使用 Documentation/process/coding-style.rst 中所描述的 Linux 代码风 - 格。如果你的某些代码段（例如那些与 Windows 驱动程序包共 - 享的代码段）需要使用其他格式，而你却只希望维护一份代码， - 那么请将它们很好地区分出来，并且注明原因。 - -可移植性： 请注意，指针并不永远是 32 位的，不是所有的计算机都使用小 - 尾模式 (little endian) 存储数据，不是所有的人都拥有浮点 - 单元，不要随便在你的驱动程序里嵌入 x86 汇编指令。只能在 - x86 上运行的驱动程序一般是不受欢迎的。虽然你可能只有 x86 - 硬件，很难测试驱动程序在其他平台上是否可用，但是确保代码 - 可以被轻松地移植却是很简单的。 - -清晰度： 做到所有人都能修补这个驱动程序将会很有好处，因为这样你将 - 会直接收到修复的补丁而不是 bug 报告。如果你提交一个试图 - 隐藏硬件工作机理的驱动程序，那么它将会被扔进废纸篓。 - -电源管理： 因为 Linux 正在被很多移动设备和桌面系统使用，所以你的驱 - 动程序也很有可能被使用在这些设备上。它应该支持最基本的电 - 源管理，即在需要的情况下实现系统级休眠和唤醒要用到的 - .suspend 和 .resume 函数。你应该检查你的驱动程序是否能正 - 确地处理休眠与唤醒，如果实在无法确认，请至少把 .suspend - 函数定义成返回 -ENOSYS（功能未实现）错误。你还应该尝试确 - 保你的驱动在什么都不干的情况下将耗电降到最低。要获得驱动 - 程序测试的指导，请参阅 - Documentation/power/drivers-testing.rst。有关驱动程序电 - 源管理问题相对全面的概述，请参阅 - Documentation/driver-api/pm/devices.rst。 - -管理： 如果一个驱动程序的作者还在进行有效的维护，那么通常除了那 - 些明显正确且不需要任何检查的补丁以外，其他所有的补丁都会 - 被转发给作者。如果你希望成为驱动程序的联系人和更新者，最 - 好在代码注释中写明并且在 MAINTAINERS 文件中加入这个驱动 - 程序的条目。 - -不影响设备驱动能否被接受的条件 ------------------------------- - -供应商： 由硬件供应商来维护驱动程序通常是一件好事。不过，如果源码 - 树里已经有其他人提供了可稳定工作的驱动程序，那么请不要期 - 望“我是供应商”会成为内核改用你的驱动程序的理由。理想的情 - 况是：供应商与现有驱动程序的作者合作，构建一个统一完美的 - 驱动程序。 - -作者： 驱动程序是由大的 Linux 公司研发还是由你个人编写，并不影 - 响其是否能被内核接受。没有人对内核源码树享有特权。只要你 - 充分了解内核社区，你就会发现这一点。 - - -资源列表 --------- - -Linux 内核主源码树： - ftp.??.kernel.org:/pub/linux/kernel/... - ?? == 你的国家代码，例如 "cn"、"us"、"uk"、"fr" 等等 - -Linux 内核邮件列表： - linux-kernel@vger.kernel.org - [可通过向majordomo@vger.kernel.org发邮件来订阅] - -Linux 设备驱动程序，第三版（探讨 2.6.10 版内核）： - http://lwn.net/Kernel/LDD3/ （免费版） - -LWN.net: - 每周内核开发活动摘要 - http://lwn.net/ - - 2.6 版中 API 的变更： - - http://lwn.net/Articles/2.6-kernel-api/ - - 将旧版内核的驱动程序移植到 2.6 版： - - http://lwn.net/Articles/driver-porting/ - -内核新手(KernelNewbies): - 为新的内核开发者提供文档和帮助 - http://kernelnewbies.org/ - -Linux USB项目： - http://www.linux-usb.org/ - -写内核驱动的“不要”（Arjan van de Ven著）: - http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf - -内核清洁工 (Kernel Janitor): - http://kernelnewbies.org/KernelJanitors diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst index 1bb4271ab420..f8978f02057c 100644 --- a/Documentation/translations/zh_CN/process/submitting-patches.rst +++ b/Documentation/translations/zh_CN/process/submitting-patches.rst @@ -1,144 +1,92 @@ -.. _cn_submittingpatches: +.. SPDX-License-Identifier: GPL-2.0-or-later .. include:: ../disclaimer-zh_CN.rst -:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +.. _cn_submittingpatches: + +:Original: Documentation/process/submitting-patches.rst -译者:: +:译者: + - 钟宇 TripleX Chung <xxx.phy@gmail.com> + - 时奎亮 Alex Shi <alexs@kernel.org> + - 吴想成 Wu XiangCheng <bobwxc@email.cn> - 中文版维护者： 钟宇 TripleX Chung <xxx.phy@gmail.com> - 中文版翻译者： 钟宇 TripleX Chung <xxx.phy@gmail.com> - 时奎亮 Alex Shi <alex.shi@linux.alibaba.com> - 中文版校译者： 李阳 Li Yang <leoyang.li@nxp.com> - 王聪 Wang Cong <xiyou.wangcong@gmail.com> +:校译: + - 李阳 Li Yang <leoyang.li@nxp.com> + - 王聪 Wang Cong <xiyou.wangcong@gmail.com> -如何让你的改动进入内核 -====================== +提交补丁：如何让你的改动进入内核 +================================ 对于想要将改动提交到 Linux 内核的个人或者公司来说，如果不熟悉“规矩”， -提交的流程会让人畏惧。本文档收集了一系列建议，这些建议可以大大的提高你 +提交的流程会让人畏惧。本文档包含了一系列建议，可以大大提高你 的改动被接受的机会. -以下文档含有大量简洁的建议， 具体请见： -:ref:`Documentation/process <development_process_main>` -同样，:ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>` -给出在提交代码前需要检查的项目的列表。如果你在提交一个驱动程序，那么 -同时阅读一下: -:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` +本文档以较为简洁的行文给出了大量建议。关于内核开发流程如何进行的详细信息， +参见： Documentation/translations/zh_CN/process/development-process.rst 。 +Documentation/translations/zh_CN/process/submit-checklist.rst 给出了一系列 +提交补丁之前要检查的事项。设备树相关的补丁，请参阅 +Documentation/devicetree/bindings/submitting-patches.rst 。 -其中许多步骤描述了Git版本控制系统的默认行为；如果您使用Git来准备补丁， -您将发现它为您完成的大部分机械工作，尽管您仍然需要准备和记录一组合理的 -补丁。一般来说，使用git将使您作为内核开发人员的生活更轻松。 +本文档假设您正在使用 ``git`` 准备你的补丁。如果您不熟悉 ``git`` ，最好学习 +如何使用它，这将使您作为内核开发人员的生活变得更加轻松。 +部分子系统和维护人员的树有一些关于其工作流程和要求的额外信息，请参阅 +Documentation/process/maintainer-handbooks.rst 。 -0) 获取当前源码树 ------------------ +获取当前源码树 +-------------- -如果您没有一个可以使用当前内核源代码的存储库，请使用git获取一个。您将要 -从主线存储库开始，它可以通过以下方式获取:: +如果您手头没有当前内核源代码的存储库，请使用 ``git`` 获取一份。您需要先获取 +主线存储库，它可以通过以下命令拉取:: - git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git -但是，请注意，您可能不希望直接针对主线树进行开发。大多数子系统维护人员运 +但是，请注意，您可能不想直接针对主线树进行开发。大多数子系统维护人员运 行自己的树，并希望看到针对这些树准备的补丁。请参见MAINTAINERS文件中子系 -统的 **T:** 项以查找该树，或者简单地询问维护者该树是否未在其中列出。 - -仍然可以通过tarballs下载内核版本（如下一节所述），但这是进行内核开发的 -一种困难的方式。 - -1) "diff -up" -------------- - -使用 "diff -up" 或者 "diff -uprN" 来创建补丁。 - -所有内核的改动，都是以补丁的形式呈现的，补丁由 diff(1) 生成。创建补丁的 -时候，要确认它是以 "unified diff" 格式创建的，这种格式由 diff(1) 的 '-u' -参数生成。而且，请使用 '-p' 参数，那样会显示每个改动所在的C函数，使得 -产生的补丁容易读得多。补丁应该基于内核源代码树的根目录，而不是里边的任 -何子目录。 - -为一个单独的文件创建补丁，一般来说这样做就够了:: - - SRCTREE=linux - MYFILE=drivers/net/mydriver.c +统的 **T:** 项以查找该树，或者直接询问维护者该树是否未在其中列出。 - cd $SRCTREE - cp $MYFILE $MYFILE.orig - vi $MYFILE # make your change - cd .. - diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch +.. _zh_describe_changes: -为多个文件创建补丁，你可以解开一个没有修改过的内核源代码树，然后和你自 -己的代码树之间做 diff 。例如:: - - MYSRC=/devel/linux - - tar xvfz linux-3.19.tar.gz - mv linux-3.19 linux-3.19-vanilla - diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ - linux-3.19-vanilla $MYSRC > /tmp/patch - -"dontdiff" 是内核在编译的时候产生的文件的列表，列表中的文件在 diff(1) -产生的补丁里会被跳过。 - -确定你的补丁里没有包含任何不属于这次补丁提交的额外文件。记得在用diff(1) -生成补丁之后，审阅一次补丁，以确保准确。 - -如果你的改动很散乱，你应该研究一下如何将补丁分割成独立的部分，将改动分 -割成一系列合乎逻辑的步骤。这样更容易让其他内核开发者审核，如果你想你的 -补丁被接受，这是很重要的。请参阅： -:ref:`cn_split_changes` - -如果你用 ``git`` , ``git rebase -i`` 可以帮助你这一点。如果你不用 ``git``, -``quilt`` <http://savannah.nongnu.org/projects/quilt> 另外一个流行的选择。 - -.. _cn_describe_changes: - -2) 描述你的改动 ---------------- +描述你的改动 +------------ 描述你的问题。无论您的补丁是一行错误修复还是5000行新功能，都必须有一个潜在 -的问题激励您完成这项工作。让审稿人相信有一个问题值得解决，让他们读完第一段 -是有意义的。 +的问题激励您完成这项工作。说服审阅者相信有一个问题值得解决，让他们读完第一段 +后就能明白这一点。 描述用户可见的影响。直接崩溃和锁定是相当有说服力的，但并不是所有的错误都那么 -明目张胆。即使在代码审查期间发现了这个问题，也要描述一下您认为它可能对用户产 +明目张胆。即使在代码审阅期间发现了这个问题，也要描述一下您认为它可能对用户产 生的影响。请记住，大多数Linux安装运行的内核来自二级稳定树或特定于供应商/产品 的树，只从上游精选特定的补丁，因此请包含任何可以帮助您将更改定位到下游的内容： 触发的场景、DMESG的摘录、崩溃描述、性能回归、延迟尖峰、锁定等。 -量化优化和权衡。如果您声称在性能、内存消耗、堆栈占用空间或二进制大小方面有所 -改进，请包括支持它们的数字。但也要描述不明显的成本。优化通常不是免费的，而是 -在CPU、内存和可读性之间进行权衡；或者，探索性的工作，在不同的工作负载之间进 +质量优化和权衡。如果您声称在性能、内存消耗、堆栈占用空间或二进制大小方面有所 +改进，请包括支持它们的数据。但也要描述不明显的成本。优化通常不是零成本的，而是 +在CPU、内存和可读性之间进行权衡；或者，做探索性的工作，在不同的工作负载之间进 行权衡。请描述优化的预期缺点，以便审阅者可以权衡成本和收益。 -一旦问题建立起来，就要详细地描述一下您实际在做什么。对于审阅者来说，用简单的 -英语描述代码的变化是很重要的，以验证代码的行为是否符合您的意愿。 +提出问题之后，就要详细地描述一下您实际在做的技术细节。对于审阅者来说，用简练的 +英语描述代码的变化是很重要的，以验证代码的行为是否符合您的意图。 -如果您将补丁描述写在一个表单中，这个表单可以很容易地作为“提交日志”放入Linux -的源代码管理系统git中，那么维护人员将非常感谢您。见 :ref:`cn_explicit_in_reply_to`. +如果您将补丁描述写成“标准格式”，可以很容易地作为“提交日志”放入Linux的源代 +码管理系统 ``git`` 中，那么维护人员将非常感谢您。 +参见 :ref:`zh_the_canonical_patch_format` 。 每个补丁只解决一个问题。如果你的描述开始变长，这就表明你可能需要拆分你的补丁。 -请见 :ref:`cn_split_changes` +请见 :ref:`zh_split_changes` 。 -提交或重新提交修补程序或修补程序系列时，请包括完整的修补程序说明和理由。不要 +提交或重新提交补丁或补丁系列时，请包括完整的补丁说明和理由。不要 只说这是补丁（系列）的第几版。不要期望子系统维护人员引用更早的补丁版本或引用 URL来查找补丁描述并将其放入补丁中。也就是说，补丁（系列）及其描述应该是独立的。 -这对维护人员和审查人员都有好处。一些评审者可能甚至没有收到补丁的早期版本。 +这对维护人员和审阅者都有好处。一些审阅者可能甚至没有收到补丁的早期版本。 -描述你在命令语气中的变化，例如“make xyzzy do frotz”而不是“[这个补丁]make -xyzzy do frotz”或“[我]changed xyzzy to do frotz”，就好像你在命令代码库改变 +用祈使句描述你的变更，例如“make xyzzy do frotz”而不是“[This patch]make +xyzzy do frotz”或“[I]changed xyzzy to do frotz”，就好像你在命令代码库改变 它的行为一样。 -如果修补程序修复了一个记录的bug条目，请按编号和URL引用该bug条目。如果补丁来 -自邮件列表讨论，请给出邮件列表存档的URL；使用带有 ``Message-ID`` 的 -https://lkml.kernel.org/ 重定向，以确保链接不会过时。 - -但是，在没有外部资源的情况下，尽量让你的解释可理解。除了提供邮件列表存档或 -bug的URL之外，还要总结需要提交补丁的相关讨论要点。 - -如果您想要引用一个特定的提交，不要只引用提交的 SHA-1 ID。还请包括提交的一行 +如果您想要引用一个特定的提交，不要只引用提交的SHA-1 ID。还请包括提交的一行 摘要，以便于审阅者了解它是关于什么的。例如:: Commit e21d2170f36602ae2708 ("video: remove unnecessary @@ -146,82 +94,104 @@ bug的URL之外，还要总结需要提交补丁的相关讨论要点。 platform_set_drvdata(), but left the variable "dev" unused, delete it. -您还应该确保至少使用前12位 SHA-1 ID. 内核存储库包含*许多*对象，使与较短的ID +您还应该确保至少使用前12位SHA-1 ID。内核存储库包含 *许多* 对象，使较短的ID 发生冲突的可能性很大。记住，即使现在不会与您的六个字符ID发生冲突，这种情况 -可能五年后改变。 +也可能在五年后改变。 + +如果该变更的相关讨论或背景信息可以在网上查阅，请加上“Link:”标签指向它。例如 +你的补丁修复了一个缺陷，需要添加一个带有URL的标签指向邮件列表存档或缺陷跟踪器 +的相关报告；如果该补丁是由一些早先邮件列表讨论或网络上的记录引起的，请指向它。 + +当链接到邮件列表存档时，请首选lore.kernel.org邮件存档服务。用邮件中的 +``Message-ID`` 头（去掉尖括号）可以创建链接URL。例如:: + + Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + +请检查该链接以确保可用且指向正确的邮件。 -如果修补程序修复了特定提交中的错误，例如，使用 ``git bisct`` ，请使用带有前 -12个字符SHA-1 ID 的"Fixes:"标记和单行摘要。为了简化不要将标记拆分为多个， -行、标记不受分析脚本“75列换行”规则的限制。例如:: +不过，在没有外部资源的情况下，也要尽量让你的解释可理解。除了提供邮件列表存档或 +缺陷的URL之外，还要需要总结该补丁的相关讨论要点。 - Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") +如果补丁修复了特定提交中的错误，例如使用 ``git bisct`` 发现了一个问题，请使用 +带有前12个字符SHA-1 ID的“Fixes:”标签和单行摘要。为了简化解析脚本，不要将该 +标签拆分为多行，标签不受“75列换行”规则的限制。例如:: -下列 ``git config`` 设置可以添加让 ``git log``, ``git show`` 漂亮的显示格式:: + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") + +下列 ``git config`` 设置可以让 ``git log``, ``git show`` 增加上述风格的显示格式:: [core] abbrev = 12 [pretty] fixes = Fixes: %h (\"%s\") -.. _cn_split_changes: +使用示例:: + + $ git log -1 --pretty=fixes 54a4f0239f2e + Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") -3) 拆分你的改动 ---------------- +.. _zh_split_changes: -将每个逻辑更改分隔成一个单独的补丁。 +拆分你的改动 +------------ + +将每个 **逻辑更改** 拆分成一个单独的补丁。 例如，如果你的改动里同时有bug修正和性能优化，那么把这些改动拆分到两个或 -者更多的补丁文件中。如果你的改动包含对API的修改，并且修改了驱动程序来适 -应这些新的API，那么把这些修改分成两个补丁。 +者更多的补丁文件中。如果你的改动包含对API的修改，并且增加了一个使用该新API +的驱动，那么把这些修改分成两个补丁。 另一方面，如果你将一个单独的改动做成多个补丁文件，那么将它们合并成一个 单独的补丁文件。这样一个逻辑上单独的改动只被包含在一个补丁文件里。 -如果有一个补丁依赖另外一个补丁来完成它的改动，那没问题。简单的在你的补 -丁描述里指出“这个补丁依赖某补丁”就好了。 +需要记住的一点是，每个补丁的更改都应易于理解，以便审阅者验证。每个补丁都应该 +对其价值进行阐述。 + +如果有一个补丁依赖另外一个补丁来完成它的改动，那没问题。直接在你的补 +丁描述里指出 **“这个补丁依赖某补丁”** 就好了。 -在将您的更改划分为一系列补丁时，要特别注意确保内核在系列中的每个补丁之后 -都能正常构建和运行。使用 ``git bisect`` 来追踪问题的开发者可能会在任何时 -候分割你的补丁系列；如果你在中间引入错误，他们不会感谢你。 +在将您的更改划分为一系列补丁时，要特别注意确保内核在应用系列中的每个补丁之后 +都能正常构建和运行。使用 ``git bisect`` 来追踪问题的开发者可能会在任何地方分 +割你的补丁系列；如果你在中间引入错误，他们不会感谢你。 -如果你不能将补丁浓缩成更少的文件，那么每次大约发送出15个，然后等待审查 +如果你不能将补丁系列浓缩得更小，那么每次大约发送出15个补丁，然后等待审阅 和集成。 -4) 检查你的更改风格 -------------------- +检查你的更改风格 +---------------- -检查您的补丁是否存在基本样式冲突，详细信息可在 -:ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>` -中找到。如果不这样做，只会浪费审稿人的时间，并且会导致你的补丁被拒绝，甚至 +检查您的补丁是否违反了基本样式规定，详细信息参见 +Documentation/translations/zh_CN/process/coding-style.rst +中找到。如果不这样做，只会浪费审阅者的时间，并且会导致你的补丁被拒绝，甚至 可能没有被阅读。 一个重要的例外是在将代码从一个文件移动到另一个文件时——在这种情况下，您不应 该在移动代码的同一个补丁中修改移动的代码。这清楚地描述了移动代码和您的更改 -的行为。这大大有助于审查实际差异，并允许工具更好地跟踪代码本身的历史。 +的行为。这大大有助于审阅实际差异，并允许工具更好地跟踪代码本身的历史。 在提交之前，使用补丁样式检查程序检查补丁（scripts/check patch.pl）。不过， 请注意，样式检查程序应该被视为一个指南，而不是作为人类判断的替代品。如果您 -的代码看起来更好，但有违规行为，那么最好不要使用它。 +的代码看起来更好，但有违规行为，那么最好别管它。 检查者报告三个级别： - ERROR：很可能出错的事情 - - WARNING：需要仔细审查的事项 + - WARNING：需要仔细审阅的事项 - CHECK：需要思考的事情 您应该能够判断您的补丁中存在的所有违规行为。 -5) 选择补丁收件人 ------------------ +选择补丁收件人 +-------------- -您应该总是在任何补丁上复制相应的子系统维护人员，以获得他们维护的代码；查看 +您应该总是知会任何补丁相应代码的子系统维护人员；查看 维护人员文件和源代码修订历史记录，以了解这些维护人员是谁。脚本 -scripts/get_Maintainer.pl在这个步骤中非常有用。如果您找不到正在工作的子系统 +scripts/get_maintainer.pl在这个步骤中非常有用。如果您找不到正在工作的子系统 的维护人员，那么Andrew Morton（akpm@linux-foundation.org）将充当最后的维护 人员。 -您通常还应该选择至少一个邮件列表来接收补丁集的。linux-kernel@vger.kernel.org -作为最后一个解决办法的列表，但是这个列表上的体积已经引起了许多开发人员的拒绝。 +您通常还应该选择至少一个邮件列表来接收补丁集的副本。linux-kernel@vger.kernel.org +是所有补丁的默认列表，但是这个列表的流量已经导致了许多开发人员不再看它。 在MAINTAINERS文件中查找子系统特定的列表；您的补丁可能会在那里得到更多的关注。 不过，请不要发送垃圾邮件到无关的列表。 @@ -231,212 +201,170 @@ http://vger.kernel.org/vger-lists.html 上找到它们的列表。不过，也 不要一次发送超过15个补丁到vger邮件列表！！！！ -Linus Torvalds 是决定改动能否进入 Linux 内核的最终裁决者。他的 e-mail -地址是 <torvalds@linux-foundation.org> 。他收到的 e-mail 很多，所以一般 -的说，最好别给他发 e-mail。 - -如果您有修复可利用安全漏洞的补丁，请将该补丁发送到 security@kernel.org。对于 -严重的bug，可以考虑短期暂停以允许分销商向用户发布补丁；在这种情况下，显然不应 -将补丁发送到任何公共列表。 +Linus Torvalds是决定改动能否进入 Linux 内核的最终裁决者。他的邮件地址是 +torvalds@linux-foundation.org 。他收到的邮件很多，所以一般来说最好 **别** +给他发邮件。 -修复已发布内核中严重错误的补丁程序应该指向稳定版维护人员，方法是放这样的一行:: +如果您有修复可利用安全漏洞的补丁，请将该补丁发送到 security@kernel.org 。对于 +严重的bug，可以考虑短期禁令以允许分销商（有时间）向用户发布补丁；在这种情况下， +显然不应将补丁发送到任何公共列表。 +参见 Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。 - Cc: stable@vger.kernel.org +修复已发布内核中严重错误的补丁程序应该抄送给稳定版维护人员，方法是把以下列行 +放进补丁的签准区（注意，不是电子邮件收件人）:: -进入补丁的签准区（注意，不是电子邮件收件人）。除了这个文件之外，您还应该阅读 -:ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` + Cc: stable@vger.kernel.org -但是，请注意，一些子系统维护人员希望得出他们自己的结论，即哪些补丁应该被放到 -稳定的树上。尤其是网络维护人员，不希望看到单个开发人员在补丁中添加像上面这样 -的行。 +除了本文件之外，您还应该阅读 +Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。 -如果更改影响到用户和内核接口，请向手册页维护人员（如维护人员文件中所列）发送 +如果更改影响到用户侧内核接口，请向手册页维护人员（如维护人员文件中所列）发送 手册页补丁，或至少发送更改通知，以便一些信息进入手册页。还应将用户空间API -更改复制到 linux-api@vger.kernel.org。 - -对于小的补丁，你也许会CC到搜集琐碎补丁的邮件列表(Trivial Patch Monkey) -trivial@kernel.org，那里专门收集琐碎的补丁。下面这样的补丁会被看作“琐碎的” -补丁： - - - 文档的拼写修正。 - - 修正会影响到 grep(1) 的拼写。 - - 警告信息修正(频繁的打印无用的警告是不好的。) - - 编译错误修正（代码逻辑的确是对的，只是编译有问题。） - - 运行时修正（只要真的修正了错误。） - - 移除使用了被废弃的函数/宏的代码(例如 check_region。) - - 联系方式和文档修正。 - - 用可移植的代码替换不可移植的代码（即使在体系结构相关的代码中，既然有 - - 人拷贝，只要它是琐碎的） - - 任何文件的作者/维护者对该文件的改动（例如 patch monkey 在重传模式下） - -(译注，关于“琐碎补丁”的一些说明：因为原文的这一部分写得比较简单，所以不得不 -违例写一下译注。"trivial"这个英文单词的本意是“琐碎的，不重要的。”但是在这里 -有稍微有一些变化，例如对一些明显的NULL指针的修正，属于运行时修正，会被归类 -到琐碎补丁里。虽然NULL指针的修正很重要，但是这样的修正往往很小而且很容易得到 -检验，所以也被归入琐碎补丁。琐碎补丁更精确的归类应该是 -“simple, localized & easy to verify”，也就是说简单的，局部的和易于检验的。 -trivial@kernel.org邮件列表的目的是针对这样的补丁，为提交者提供一个中心，来 -降低提交的门槛。) - -6) 没有 MIME 编码，没有链接，没有压缩，没有附件，只有纯文本 ------------------------------------------------------------ +更改抄送到 linux-api@vger.kernel.org 。 + + +不要MIME编码，不要链接，不要压缩，不要附件，只要纯文本 +------------------------------------------------------ Linus 和其他的内核开发者需要阅读和评论你提交的改动。对于内核开发者来说 -，可以“引用”你的改动很重要，使用一般的 e-mail 工具，他们就可以在你的 +，可以“引用”你的改动很重要，使用一般的邮件工具，他们就可以在你的 代码的任何位置添加评论。 -因为这个原因，所有的提交的补丁都是 e-mail 中“内嵌”的。 +因为这个原因，所有的提交的补丁都是邮件中“内嵌”的。最简单（和推荐）的方法就 +是使用 ``git send-email`` 。https://git-send-email.io 有 ``git send-email`` +的交互式教程。 + +如果你选择不用 ``git send-email`` ： .. warning:: - 如果你使用剪切-粘贴你的补丁，小心你的编辑器的自动换行功能破坏你的补丁 -不要将补丁作为 MIME 编码的附件，不管是否压缩。很多流行的 e-mail 软件不 -是任何时候都将 MIME 编码的附件当作纯文本发送的，这会使得别人无法在你的 -代码中加评论。另外，MIME 编码的附件会让 Linus 多花一点时间来处理，这就 -降低了你的改动被接受的可能性。 + 如果你使用剪切-粘贴你的补丁，小心你的编辑器的自动换行功能破坏你的补丁 -例外：如果你的邮递员弄坏了补丁，那么有人可能会要求你使用mime重新发送补丁 +不要将补丁作为MIME编码的附件，不管是否压缩。很多流行的邮件软件不 +是任何时候都将MIME编码的附件当作纯文本发送的，这会使得别人无法在你的 +代码中加评论。另外，MIME编码的附件会让Linus多花一点时间来处理，这就 +降低了你的改动被接受的可能性。 -请参阅 :ref:`Documentation/translations/zh_CN/process/email-clients.rst <cn_email_clients>` -以获取有关配置电子邮件客户端以使其不受影响地发送修补程序的提示。 +例外：如果你的邮路损坏了补丁，那么有人可能会要求你使用MIME重新发送补丁。 -7) e-mail 的大小 ----------------- +请参阅 Documentation/translations/zh_CN/process/email-clients.rst +以获取有关配置电子邮件客户端以使其不受影响地发送补丁的提示。 -大的改动对邮件列表不合适，对某些维护者也不合适。如果你的补丁，在不压缩 -的情况下，超过了300kB，那么你最好将补丁放在一个能通过 internet 访问的服 -务器上，然后用指向你的补丁的 URL 替代。但是请注意，如果您的补丁超过了 -300kb，那么它几乎肯定需要被破坏。 +回复审阅意见 +------------ -8）回复评审意见 ---------------- +你的补丁几乎肯定会得到审阅者对补丁改进方法的评论（以回复邮件的形式）。您必须 +对这些评论作出回应；让补丁被忽略的一个好办法就是忽略审阅者的意见。直接回复邮 +件来回应意见即可。不会导致代码更改的意见或问题几乎肯定会带来注释或变更日志的 +改变，以便下一个审阅者更好地了解正在发生的事情。 -你的补丁几乎肯定会得到评审者对补丁改进方法的评论。您必须对这些评论作出 -回应；让补丁被忽略的一个好办法就是忽略审阅者的意见。不会导致代码更改的 -意见或问题几乎肯定会带来注释或变更日志的改变，以便下一个评审者更好地了解 -正在发生的事情。 +一定要告诉审阅者你在做什么改变，并感谢他们的时间。代码审阅是一个累人且耗时的 +过程，审阅者有时会变得暴躁。即使在这种情况下，也要礼貌地回应并解决他们指出的 +问题。当发送下一版时，在封面邮件或独立补丁里加上 ``patch changelog`` 说明与 +前一版本的不同之处（参见 :ref:`zh_the_canonical_patch_format` ）。 -一定要告诉审稿人你在做什么改变，并感谢他们的时间。代码审查是一个累人且 -耗时的过程，审查人员有时会变得暴躁。即使在这种情况下，也要礼貌地回应并 -解决他们指出的问题。 +.. _zh_resend_reminders: -9）不要泄气或不耐烦 -------------------- +不要泄气或不耐烦 +---------------- -提交更改后，请耐心等待。审阅者是忙碌的人，可能无法立即访问您的修补程序。 +提交更改后，请耐心等待。审阅者是大忙人，可能无法立即审阅您的补丁。 -曾几何时，补丁曾在没有评论的情况下消失在空白中，但开发过程比现在更加顺利。 +曾几何时，补丁曾在没收到评论的情况下消失在虚空中，但现在开发过程应该更加顺利了。 您应该在一周左右的时间内收到评论；如果没有收到评论，请确保您已将补丁发送 -到正确的位置。在重新提交或联系审阅者之前至少等待一周-在诸如合并窗口之类的 +到正确的位置。在重新提交或联系审阅者之前至少等待一周——在诸如合并窗口之类的 繁忙时间可能更长。 -10）主题中包含 PATCH --------------------- +在等了几个星期后，用带RESEND的主题重发补丁也是可以的:: -由于到linus和linux内核的电子邮件流量很高，通常会在主题行前面加上[PATCH] -前缀. 这使Linus和其他内核开发人员更容易将补丁与其他电子邮件讨论区分开。 + [PATCH Vx RESEND] sub/sys: Condensed patch summary -11）签署你的作品-开发者原始认证 -------------------------------- +当你发布补丁（系列）修改版的时候，不要加上“RESEND”——“RESEND”只适用于重 +新提交之前未经修改的补丁（系列）。 -为了加强对谁做了何事的追踪，尤其是对那些透过好几层的维护者的补丁，我们 -建议在发送出去的补丁上加一个 “sign-off” 的过程。 +主题中包含 PATCH +---------------- + +由于到Linus和linux-kernel的电子邮件流量很高，通常会在主题行前面加上[PATCH] +前缀。这使Linus和其他内核开发人员更容易将补丁与其他电子邮件讨论区分开。 + +``git send-email`` 会自动为你加上。 + +签署你的作品——开发者来源认证 +------------------------------ + +为了加强对谁做了何事的追踪，尤其是对那些透过好几层维护者才最终到达的补丁，我 +们在通过邮件发送的补丁上引入了“签署（sign-off）”流程。 -"sign-off" 是在补丁的注释的最后的简单的一行文字，认证你编写了它或者其他 +“签署”是在补丁注释最后的一行简单文字，认证你编写了它或者其他 人有权力将它作为开放源代码的补丁传递。规则很简单：如果你能认证如下信息: -开发者来源证书 1.1 +开发者来源认证 1.1 ^^^^^^^^^^^^^^^^^^ 对于本项目的贡献，我认证如下信息： - （a）这些贡献是完全或者部分的由我创建，我有权利以文件中指出 + (a) 这些贡献是完全或者部分的由我创建，我有权利以文件中指出 的开放源代码许可证提交它；或者 - （b）这些贡献基于以前的工作，据我所知，这些以前的工作受恰当的开放 - 源代码许可证保护，而且，根据许可证，我有权提交修改后的贡献， + + (b) 这些贡献基于以前的工作，据我所知，这些以前的工作受恰当的开放 + 源代码许可证保护，而且，根据文件中指出的许可证，我有权提交修改后的贡献， 无论是完全还是部分由我创造，这些贡献都使用同一个开放源代码许可证 - （除非我被允许用其它的许可证），正如文件中指出的；或者 - （c）这些贡献由认证（a），（b）或者（c）的人直接提供给我，而 + （除非我被允许用其它的许可证）；或者 + + (c) 这些贡献由认证（a），（b）或者（c）的人直接提供给我，而 且我没有修改它。 - （d）我理解并同意这个项目和贡献是公开的，贡献的记录（包括我 - 一起提交的个人记录，包括 sign-off ）被永久维护并且可以和这个项目 + + (d) 我理解并同意这个项目和贡献是公开的，贡献的记录（包括我 + 一起提交的个人记录，包括sign-off）被永久维护并且可以和这个项目 或者开放源代码的许可证同步地再发行。 那么加入这样一行:: - Signed-off-by: Random J Developer <random@developer.example.org> - -使用你的真名（抱歉，不能使用假名或者匿名。） - -有人在最后加上标签。现在这些东西会被忽略，但是你可以这样做，来标记公司 -内部的过程，或者只是指出关于 sign-off 的一些特殊细节。 - -如果您是子系统或分支维护人员，有时需要稍微修改收到的补丁，以便合并它们， -因为树和提交者中的代码不完全相同。如果你严格遵守规则（c），你应该要求提交者 -重新发布，但这完全是在浪费时间和精力。规则（b）允许您调整代码，但是更改一个 -提交者的代码并让他认可您的错误是非常不礼貌的。要解决此问题，建议在最后一个 -由签名行和您的行之间添加一行，指示更改的性质。虽然这并不是强制性的，但似乎 -在描述前加上您的邮件和/或姓名（全部用方括号括起来），这足以让人注意到您对最 -后一分钟的更改负有责任。例如:: - - Signed-off-by: Random J Developer <random@developer.example.org> - [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] - Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> - -如果您维护一个稳定的分支机构，同时希望对作者进行致谢、跟踪更改、合并修复并 -保护提交者不受投诉，那么这种做法尤其有用。请注意，在任何情况下都不能更改作者 -的ID（From 头），因为它是出现在更改日志中的标识。 - -对回合（back-porters）的特别说明：在提交消息的顶部（主题行之后）插入一个补丁 -的起源指示似乎是一种常见且有用的实践，以便于跟踪。例如，下面是我们在3.x稳定 -版本中看到的内容:: - - Date: Tue Oct 7 07:26:38 2014 -0400 - - libata: Un-break ATA blacklist - - commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. - -还有， 这里是一个旧版内核中的一个回合补丁:: + Signed-off-by: Random J Developer <random@developer.example.org> - Date: Tue May 13 22:12:27 2008 +0200 +使用你的真名（抱歉，不能使用假名或者匿名。）如果使用 ``git commit -s`` 的话 +将会自动完成。撤销也应当包含“Signed-off-by”， ``git revert -s`` 会帮你搞定。 - wireless, airo: waitbusy() won't delay +有些人会在最后加上额外的标签。现在这些东西会被忽略，但是你可以这样做，来标记 +公司内部的过程，或者只是指出关于签署的一些特殊细节。 - [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] +作者签署之后的任何其他签署（Signed-off-by:'s）均来自处理和传递补丁的人员，但 +未参与其开发。签署链应当反映补丁传播到维护者并最终传播到Linus所经过的 **真实** +路径，首个签署指明单个作者的主要作者身份。 -12）何时使用Acked-by:，CC:，和Co-Developed by: ----------------------------------------------- +何时使用Acked-by:，CC:，和Co-Developed by: +------------------------------------------ -Singed-off-by: 标记表示签名者参与了补丁的开发，或者他/她在补丁的传递路径中。 +Singed-off-by: 标签表示签名者参与了补丁的开发，或者他/她在补丁的传递路径中。 -如果一个人没有直接参与补丁的准备或处理，但希望表示并记录他们对补丁的批准， -那么他们可以要求在补丁的变更日志中添加一个 Acked-by: +如果一个人没有直接参与补丁的准备或处理，但希望表示并记录他们对补丁的批准/赞成， +那么他们可以要求在补丁的变更日志中添加一个Acked-by:。 -Acked-by：通常由受影响代码的维护者使用，当该维护者既没有贡献也没有转发补丁时。 +Acked-by: 通常由受影响代码的维护者使用，当该维护者既没有贡献也没有转发补丁时。 -Acked-by: 不像签字人那样正式。这是一个记录，确认人至少审查了补丁，并表示接受。 -因此，补丁合并有时会手动将Acker的“Yep，looks good to me”转换为 Acked-By：（但 +Acked-by: 不像签署那样正式。这是一个记录，确认人至少审阅了补丁，并表示接受。 +因此，补丁合并有时会手动将Acker的“Yep，looks good to me”转换为 Acked-By:（但 请注意，通常最好要求一个明确的Ack）。 Acked-by：不一定表示对整个补丁的确认。例如，如果一个补丁影响多个子系统，并且 -有一个：来自一个子系统维护者，那么这通常表示只确认影响维护者代码的部分。这里 -应该仔细判断。如有疑问，应参考邮件列表档案中的原始讨论。 +有一个来自某个子系统维护者的Acked-By:，那么这通常表示只确认影响维护者代码的部 +分。这里应该仔细判断。如有疑问，应参考邮件列表存档中的原始讨论。 -如果某人有机会对补丁进行评论，但没有提供此类评论，您可以选择在补丁中添加 ``Cc:`` -这是唯一一个标签，它可以在没有被它命名的人显式操作的情况下添加，但它应该表明 -这个人是在补丁上抄送的。讨论中包含了潜在利益相关方。 +如果某人本应有机会对补丁进行评论，但没有提供此类评论，您可以选择在补丁中添加 +``Cc:`` 这是唯一可以在没有被该人明确同意的情况下添加的标签——但它应该表明 +这个人是在补丁上抄送的。此标签记录了讨论中包含的潜在利益相关方。 Co-developed-by: 声明补丁是由多个开发人员共同创建的；当几个人在一个补丁上工 -作时，它用于将属性赋予共同作者（除了 From: 所赋予的作者之外）。因为 -Co-developed-by: 表示作者身份，所以每个共同开发人：必须紧跟在相关合作作者的 -签名之后。标准的签核程序要求：标记的签核顺序应尽可能反映补丁的时间历史，而不 -管作者是通过 From ：还是由 Co-developed-by: 共同开发的。值得注意的是，最后一 -个签字人：必须始终是提交补丁的开发人员。 +作时，它用于给出共同作者（除了From:所给出的作者之外）。因为Co-developed-by: +表示作者身份，所以每个Co-developed-by:必须紧跟在相关合作作者的签署之后。标准 +签署程序要求Singed-off-by:标签的顺序应尽可能反映补丁的时间历史，无论作者是通 +过From:还是Co-developed-by:表明。值得注意的是，最后一个Singed-off-by:必须是 +提交补丁的开发人员。 -注意，当作者也是电子邮件标题“发件人：”行中列出的人时，“From: ” 标记是可选的。 +注意，如果From:作者也是电子邮件标题的From:行中列出的人，则From:标签是可选的。 -作者提交的补丁程序示例:: +被From:作者提交的补丁示例:: <changelog> @@ -446,7 +374,7 @@ Co-developed-by: 表示作者身份，所以每个共同开发人：必须紧跟 Signed-off-by: Second Co-Author <second@coauthor.example.org> Signed-off-by: From Author <from@author.example.org> -合作开发者提交的补丁示例:: +被合作开发者提交的补丁示例:: From: From Author <from@author.example.org> @@ -459,76 +387,85 @@ Co-developed-by: 表示作者身份，所以每个共同开发人：必须紧跟 Signed-off-by: Submitting Co-Author <sub@coauthor.example.org> -13）使用报告人：、测试人：、审核人：、建议人：、修复人： --------------------------------------------------------- +使用Reported-by:、Tested-by:、Reviewed-by:、Suggested-by:和Fixes: +----------------------------------------------------------------- Reported-by: 给那些发现错误并报告错误的人致谢，它希望激励他们在将来再次帮助 -我们。请注意，如果bug是以私有方式报告的，那么在使用Reported-by标记之前，请 -先请求权限。 +我们。请注意，如果bug是以私有方式报告的，那么在使用Reported-by标签之前，请 +先请求许可。此标签是为Bug设计的；请不要将其用于感谢功能请求。 -Tested-by: 标记表示补丁已由指定的人（在某些环境中）成功测试。这个标签通知 -维护人员已经执行了一些测试，为将来的补丁提供了一种定位测试人员的方法，并确 -保测试人员的信誉。 +Tested-by: 标签表示补丁已由指定的人（在某些环境中）成功测试。这个标签通知 +维护人员已经执行了一些测试，为将来的补丁提供了一种定位测试人员的方法，并彰显测试人员的功劳。 -Reviewed-by：相反，根据审查人的声明，表明该补丁已被审查并被认为是可接受的： +Reviewed-by：根据审阅者的监督声明，表明该补丁已被审阅并被认为是可接受的： -审查人的监督声明 +审阅者的监督声明 ^^^^^^^^^^^^^^^^ -通过提供我的 Reviewed-by，我声明： +通过提供我的Reviewed-by:标签，我声明： - (a) 我已经对这个补丁进行了一次技术审查，以评估它是否适合被包含到 + (a) 我已经对这个补丁进行了一次技术审阅，以评估它是否适合被包含到 主线内核中。 (b) 与补丁相关的任何问题、顾虑或问题都已反馈给提交者。我对提交者对 我的评论的回应感到满意。 - (c) 虽然这一提交可能会改进一些东西，但我相信，此时，（1）对内核 + (c) 虽然这一提交可能仍可被改进，但我相信，此时，（1）对内核 进行了有价值的修改，（2）没有包含争论中涉及的已知问题。 - (d) 虽然我已经审查了补丁并认为它是健全的，但我不会（除非另有明确 - 说明）作出任何保证或保证它将在任何给定情况下实现其规定的目的 + (d) 虽然我已经审阅了补丁并认为它是健全的，但我不会（除非另有明确 + 说明）作出任何保证或担保它会在任何给定情况下实现其规定的目的 或正常运行。 -Reviewed-by 是一种观点声明，即补丁是对内核的适当修改，没有任何遗留的严重技术 -问题。任何感兴趣的审阅者（完成工作的人）都可以为一个补丁提供一个 Review-by -标签。此标签用于向审阅者提供致谢，并通知维护者已在修补程序上完成的审阅程度。 -Reviewed-by: 当由已知了解主题区域并执行彻底检查的审阅者提供时，通常会增加 +Reviewed-by是一种观点声明，即补丁是对内核的适当修改，没有任何遗留的严重技术 +问题。任何感兴趣的审阅者（完成工作的人）都可以为一个补丁提供一个Reviewed-by +标签。此标签用于向审阅者提供致谢，并通知维护者补丁的审阅进度。 +当Reviewed-by:标签由已知了解主题区域并执行彻底检查的审阅者提供时，通常会增加 补丁进入内核的可能性。 +一旦从测试人员或审阅者的“Tested-by”和“Reviewed-by”标签出现在邮件列表中， +作者应在发送下一个版本时将其添加到适用的补丁中。但是，如果补丁在以下版本中发 +生了实质性更改，这些标签可能不再适用，因此应该删除。通常，在补丁更改日志中 +（在 ``---`` 分隔符之后）应该提到删除某人的测试者或审阅者标签。 + Suggested-by: 表示补丁的想法是由指定的人提出的，并确保将此想法归功于指定的 人。请注意，未经许可，不得添加此标签，特别是如果该想法未在公共论坛上发布。 -这就是说，如果我们勤快地致谢我们的创意者，他们很有希望在未来得到鼓舞，再次 +也就是说，如果我们勤快地致谢创意提供者，他们将受到鼓舞，很有希望在未来再次 帮助我们。 -Fixes: 指示补丁在以前的提交中修复了一个问题。它可以很容易地确定错误的来源， -这有助于检查错误修复。这个标记还帮助稳定内核团队确定应该接收修复的稳定内核 -版本。这是指示补丁修复的错误的首选方法。请参阅 :ref:`cn_describe_changes` -描述您的更改以了解更多详细信息。 +Fixes: 指示补丁修复了之前提交的一个问题。它可以便于确定错误的来源，这有助于 +检查错误修复。这个标签还帮助稳定内核团队确定应该接收修复的稳定内核版本。这是 +指示补丁修复的错误的首选方法。请参阅 :ref:`zh_describe_changes` 了解更多信息。 -.. _cn_the_canonical_patch_format: +.. note:: -12）标准补丁格式 ----------------- + 附加Fixes:标签不会改变稳定内核规则流程，也不改变所有稳定版补丁抄送 + stable@vger.kernel.org的要求。有关更多信息，请阅读 + Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。 + +.. _zh_the_canonical_patch_format: + +标准补丁格式 +------------ 本节描述如何格式化补丁本身。请注意，如果您的补丁存储在 ``Git`` 存储库中，则 -可以使用 ``git format-patch`` 进行正确的补丁格式设置。但是，这些工具无法创建 +可以使用 ``git format-patch`` 进行正确的补丁格式化。但是，这些工具无法创建 必要的文本，因此请务必阅读下面的说明。 -标准的补丁，标题行是:: +标准的补丁标题行是:: Subject: [PATCH 001/123] 子系统:一句话概述 -标准补丁的信体存在如下部分： +标准补丁的信体包含如下部分： - - 一个 "from" 行指出补丁作者。后跟空行（仅当发送修补程序的人不是作者时才需要）。 + - 一个 ``from`` 行指出补丁作者。后跟空行（仅当发送补丁的人不是作者时才需要）。 - - 解释的正文，行以75列包装，这将被复制到永久变更日志来描述这个补丁。 + - 说明文字，每行最长75列，这将被复制到永久变更日志来描述这个补丁。 - 一个空行 - - 上面描述的“Signed-off-by” 行，也将出现在更改日志中。 + - 上述的 ``Signed-off-by:`` 行，也将出现在更改日志中。 - 只包含 ``---`` 的标记线。 @@ -536,29 +473,29 @@ Fixes: 指示补丁在以前的提交中修复了一个问题。它可以很容 - 实际补丁（ ``diff`` 输出）。 -标题行的格式，使得对标题行按字母序排序非常的容易 - 很多 e-mail 客户端都 -可以支持 - 因为序列号是用零填充的，所以按数字排序和按字母排序是一样的。 +标题行的格式，使得对标题行按字母序排序非常的容易——很多邮件客户端都 +可以支持——因为序列号是用零填充的，所以按数字排序和按字母排序是一样的。 -e-mail 标题中的“子系统”标识哪个内核子系统将被打补丁。 +邮件标题中的“子系统”标识哪个内核子系统将被打补丁。 -e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。“一句话概述” +邮件标题中的“一句话概述”扼要的描述邮件中的补丁。“一句话概述” 不应该是一个文件名。对于一个补丁系列（“补丁系列”指一系列的多个相关补 丁），不要对每个补丁都使用同样的“一句话概述”。 -记住 e-mail 的“一句话概述”会成为该补丁的全局唯一标识。它会蔓延到 git +记住邮件的“一句话概述”会成为该补丁的全局唯一标识。它会进入 ``git`` 的改动记录里。然后“一句话概述”会被用在开发者的讨论里，用来指代这个补 -丁。用户将希望通过 google 来搜索"一句话概述"来找到那些讨论这个补丁的文 +丁。用户将希望通过搜索引擎搜索“一句话概述”来找到那些讨论这个补丁的文 章。当人们在两三个月后使用诸如 ``gitk`` 或 ``git log --oneline`` 之类 的工具查看数千个补丁时，也会很快看到它。 出于这些原因，概述必须不超过70-75个字符，并且必须描述补丁的更改以及为 -什么需要补丁。既要简洁又要描述性很有挑战性，但写得好的概述应该这样做。 +什么需要补丁。既要简洁又要描述性很有挑战性，但写得好的概述应该这样。 概述的前缀可以用方括号括起来：“Subject: [PATCH <tag>...] <概述>”。标记 不被视为概述的一部分，而是描述应该如何处理补丁。如果补丁的多个版本已发 -送出来以响应评审（即“v1，v2，v3”）或“rfc”，以指示评审请求，那么通用标记 -可能包括版本描述符。如果一个补丁系列中有四个补丁，那么各个补丁可以这样 -编号：1/4、2/4、3/4、4/4。这可以确保开发人员了解补丁应用的顺序，并且他们 +送出来以响应评审（即“v1，v2，v3”）则必须包含版本号，或包含“RFC”以指示 +评审请求。如果一个补丁系列中有四个补丁，那么各个补丁可以这样编号：1/4、2/4、 +3/4、4/4。这可以确保开发人员了解补丁应用的顺序，且 已经查看或应用了补丁系列中的所有补丁。 一些标题的例子:: @@ -566,95 +503,134 @@ e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。 Subject: [patch 2/5] ext2: improve scalability of bitmap searching Subject: [PATCHv2 001/207] x86: fix eflags tracking -"From" 行是信体里的最上面一行，具有如下格式： +``From`` 行是信体里的最上面一行，具有如下格式:: + From: Patch Author <author@example.com> -"From" 行指明在永久改动日志里，谁会被确认为作者。如果没有 "From" 行，那 -么邮件头里的 "From: " 行会被用来决定改动日志中的作者。 +``From`` 行指明在永久改动日志里，谁会被确认为作者。如果没有 ``From`` 行，那 +么邮件头里的 ``From:`` 行会被用来决定改动日志中的作者。 -说明的主题将会被提交到永久的源代码改动日志里，因此对那些早已经不记得和 -这个补丁相关的讨论细节的有能力的读者来说，是有意义的。包括补丁程序定位 -错误的（内核日志消息、OOPS消息等）症状，对于搜索提交日志以寻找适用补丁的人 -尤其有用。如果一个补丁修复了一个编译失败，那么可能不需要包含所有编译失败； +说明文字将会被提交到永久的源代码改动日志里，因此应针对那些早已经不记得和这 +个补丁相关的讨论细节的读者。包括补丁处理的故障症状（内核日志消息、oops消息 +等），这对于可能正在搜索提交日志以查找适用补丁的人特别有用。文本应该写得如 +此详细，以便在数周、数月甚至数年后阅读时，能够为读者提供所需的细节信息，以 +掌握创建补丁的 **原因** 。 + +如果一个补丁修复了一个编译失败，那么可能不需要包含 *所有* 编译失败； 只要足够让搜索补丁的人能够找到它就行了。与概述一样，既要简洁又要描述性。 -"---" 标记行对于补丁处理工具要找到哪里是改动日志信息的结束，是不可缺少 +``---`` 标记行对于补丁处理工具要找到哪里是改动日志信息的结束，是不可缺少 的。 -对于 "---" 标记之后的额外注解，一个好的用途就是用来写 diffstat，用来显 -示修改了什么文件和每个文件都增加和删除了多少行。diffstat 对于比较大的补 -丁特别有用。其余那些只是和时刻或者开发者相关的注解，不合适放到永久的改 -动日志里的，也应该放这里。 -使用 diffstat的选项 "-p 1 -w 70" 这样文件名就会从内核源代码树的目录开始 +对于 ``---`` 标记之后的额外注解，一个好的用途就是用来写 ``diffstat`` ，用来显 +示修改了什么文件和每个文件都增加和删除了多少行。 ``diffstat`` 对于比较大的补 +丁特别有用。 +使用 ``diffstat`` 的选项 ``-p 1 -w 70`` 这样文件名就会从内核源代码树的目录开始 ，不会占用太宽的空间（很容易适合80列的宽度，也许会有一些缩进。） +（ ``git`` 默认会生成合适的diffstat。） -在后面的参考资料中能看到适当的补丁格式的更多细节。 +其余那些只适用于当时或者与维护者相关的注解，不合适放到永久的改动日志里的，也 +应该放这里。较好的例子就是 ``补丁更改记录`` ，记录了v1和v2版本补丁之间的差异。 -.. _cn_explicit_in_reply_to: +请将此信息放在将变更日志与补丁的其余部分分隔开的 ``---`` 行 **之后** 。版本 +信息不是提交到git树的变更日志的一部分。只是供审阅人员使用的附加信息。如果将 +其放置在提交标记上方，则需要手动交互才能将其删除。如果它位于分隔线以下，则在 +应用补丁时会自动剥离:: -15) 明确回复邮件头(In-Reply-To) -------------------------------- + <commit message> + ... + Signed-off-by: Author <author@mail> + --- + V2 -> V3: Removed redundant helper function + V1 -> V2: Cleaned up coding style and addressed review comments -手动添加回复补丁的的标题头(In-Reply_To:) 是有帮助的（例如，使用 ``git send-email`` ） -将补丁与以前的相关讨论关联起来，例如，将bug修复程序链接到电子邮件和bug报告。 -但是，对于多补丁系列，最好避免在回复时使用链接到该系列的旧版本。这样， -补丁的多个版本就不会成为电子邮件客户端中无法管理的引用序列。如果链接有用， -可以使用 https://lkml.kernel.org/ 重定向器（例如，在封面电子邮件文本中） -链接到补丁系列的早期版本。 + path/to/file | 5+++-- + ... + +在后面的参考资料中能看到正确补丁格式的更多细节。 -16) 发送git pull请求 --------------------- +.. _zh_backtraces: -如果您有一系列补丁，那么让维护人员通过git pull操作将它们直接拉入子系统存储 -库可能是最方便的。但是，请注意，从开发人员那里获取补丁比从邮件列表中获取补 -丁需要更高的信任度。因此，许多子系统维护人员不愿意接受请求，特别是来自新的 -未知开发人员的请求。如果有疑问，您可以在封面邮件中使用pull 请求作为补丁系列 -正常发布的一个选项，让维护人员可以选择使用其中之一。 +提交消息中的回溯（Backtraces） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +回溯有助于记录导致问题的调用链。然而，并非所有回溯都有帮助。例如，早期引导调 +用链是独特而明显的。而逐字复制完整的dmesg输出则会增加时间戳、模块列表、寄存 +器和堆栈转储等分散注意力的信息。 + +因此，最有用的回溯应该从转储中提取相关信息，以更容易集中在真实问题上。下面是 +一个剪裁良好的回溯示例:: + + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Call Trace: + mba_wrmsr + update_domains + rdtgroup_mkdir + +.. _zh_explicit_in_reply_to: + +明确回复邮件头（In-Reply-To） +----------------------------- + +手动添加回复补丁的的邮件头（In-Reply_To:）是有用的（例如，使用 ``git send-email`` ）， +可以将补丁与以前的相关讨论关联起来，例如，将bug补丁链接到电子邮件和bug报告。 +但是，对于多补丁系列，最好避免在回复时使用链接到该系列的旧版本。这样， +补丁的多个版本就不会成为电子邮件客户端中无法管理的引用树。如果链接有用， +可以使用 https://lore.kernel.org/ 重定向器（例如，在封面电子邮件文本中） +链接到补丁系列的早期版本。 -pull 请求的主题行中应该有[Git Pull]。请求本身应该在一行中包含存储库名称和 -感兴趣的分支；它应该看起来像:: +给出基础树信息 +-------------- - Please pull from +当其他开发人员收到您的补丁并开始审阅时，知道应该将您的工作放到代码树历史记录 +中的什么位置通常很有用。这对于自动化持续集成流水（CI）特别有用，这些流水线试 +图运行一系列测试，以便在维护人员开始审阅之前确定提交的质量。 - git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus +如果您使用 ``git format-patch`` 生成补丁，则可以通过 ``--base`` 标志在提交中 +自动包含基础树信息。使用此选项最简单、最方便的方法是配合主题分支:: - to get these changes: + $ git checkout -t -b my-topical-branch master + Branch 'my-topical-branch' set up to track local branch 'master'. + Switched to a new branch 'my-topical-branch' + [perform your edits and commits] -pull 请求还应该包含一条整体消息，说明请求中将包含什么，一个补丁本身的 ``Git shortlog`` -以及一个显示补丁系列整体效果的 ``diffstat`` 。当然，将所有这些信息收集在一起 -的最简单方法是让 ``git`` 使用 ``git request-pull`` 命令为您完成这些工作。 + $ git format-patch --base=auto --cover-letter -o outgoing/ master + outgoing/0000-cover-letter.patch + outgoing/0001-First-Commit.patch + outgoing/... -一些维护人员（包括Linus）希望看到来自已签名提交的请求；这增加了他们对你的 -请求信心。特别是，在没有签名标签的情况下，Linus 不会从像 Github 这样的公共 -托管站点拉请求。 +当你编辑 ``outgoing/0000-cover-letter.patch`` 时，您会注意到在它的最底部有一 +行 ``base-commit:`` 尾注，它为审阅者和CI工具提供了足够的信息以正确执行 +``git am`` 而不必担心冲突:: -创建此类签名的第一步是生成一个 GNRPG 密钥，并由一个或多个核心内核开发人员对 -其进行签名。这一步对新开发人员来说可能很困难，但没有办法绕过它。参加会议是 -找到可以签署您的密钥的开发人员的好方法。 + $ git checkout -b patch-review [base-commit-id] + Switched to a new branch 'patch-review' + $ git am patches.mbox + Applying: First Commit + Applying: ... -一旦您在Git 中准备了一个您希望有人拉的补丁系列，就用 ``git tag -s`` 创建一 -个签名标记。这将创建一个新标记，标识该系列中的最后一次提交，并包含用您的私 -钥创建的签名。您还可以将changelog样式的消息添加到标记中；这是一个描述拉请求 -整体效果的理想位置。 +有关此选项的更多信息，请参阅 ``man git-format-patch`` 。 -如果维护人员将要从中提取的树不是您正在使用的存储库，请不要忘记将已签名的标记 -显式推送到公共树。 +.. note:: -生成拉请求时，请使用已签名的标记作为目标。这样的命令可以实现:: + ``--base`` 功能是在2.9.0版git中引入的。 - git request-pull master git://my.public.tree/linux.git my-signed-tag +如果您不使用git格式化补丁，仍然可以包含相同的 ``base-commit`` 尾注，以指示您 +的工作所基于的树的提交哈希。你应该在封面邮件或系列的第一个补丁中添加它，它应 +该放在 ``---`` 行的下面或所有其他内容之后，即只在你的电子邮件签名之前。 参考文献 -------- -Andrew Morton, "The perfect patch" (tpp). - <http://www.ozlabs.org/~akpm/stuff/tpp.txt> +Andrew Morton，“完美的补丁”（tpp） + <https://www.ozlabs.org/~akpm/stuff/tpp.txt> -Jeff Garzik, "Linux kernel patch submission format". +Jeff Garzik，“Linux内核补丁提交格式” <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> -Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". +Greg Kroah-Hartman，“如何惹恼内核子系统维护人员” <http://www.kroah.com/log/linux/maintainer.html> <http://www.kroah.com/log/linux/maintainer-02.html> @@ -667,16 +643,15 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". <http://www.kroah.com/log/linux/maintainer-06.html> -NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! - <https://lkml.org/lkml/2005/7/11/336> +不！！！别再发巨型补丁炸弹给linux-kernel@vger.kernel.org的人们了！ + <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> -Kernel Documentation/process/coding-style.rst: - :ref:`Documentation/translations/zh_CN/process/coding-style.rst <cn_codingstyle>` +内核 Documentation/translations/zh_CN/process/coding-style.rst -Linus Torvalds's mail on the canonical patch format: - <http://lkml.org/lkml/2005/4/7/183> +Linus Torvalds关于标准补丁格式的邮件 + <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> -Andi Kleen, "On submitting kernel patches" - Some strategies to get difficult or controversial changes in. +Andi Kleen，“提交补丁之路” + 一些帮助合入困难或有争议的变更的策略。 http://halobates.de/on-submitting-patches.pdf diff --git a/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst b/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst index 48b32ce58ef1..ded3b5d0c9a8 100644 --- a/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst +++ b/Documentation/translations/zh_CN/process/volatile-considered-harmful.rst @@ -94,8 +94,8 @@ bug并且需要对这样的代码额外仔细检查。那些试图使用volatile 注释 ---- -[1] http://lwn.net/Articles/233481/ -[2] http://lwn.net/Articles/233482/ +[1] https://lwn.net/Articles/233481/ +[2] https://lwn.net/Articles/233482/ 致谢 ---- |