diff options
Diffstat (limited to 'Documentation/translations/zh_CN/admin-guide')
6 files changed, 458 insertions, 53 deletions
diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst index be535ffaf4b0..2f6970d0a032 100644 --- a/Documentation/translations/zh_CN/admin-guide/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/index.rst @@ -36,6 +36,7 @@ Todolist: :maxdepth: 1 reporting-issues + reporting-regressions security-bugs bug-hunting bug-bisect @@ -44,7 +45,6 @@ Todolist: Todolist: -* reporting-bugs * ramoops * dynamic-debug-howto * kdump/index diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst index 0c8276109fc0..30c69e1f44fe 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst @@ -13,7 +13,7 @@ 监测数据访问 ============ -:doc:`DAMON </vm/damon/index>` 允许轻量级的数据访问监测。使用DAMON, +:doc:`DAMON </mm/damon/index>` 允许轻量级的数据访问监测。使用DAMON, 用户可以分析他们系统的内存访问模式,并优化它们。 .. toctree:: diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst index 1500bdbf338a..c976f3e33ffd 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst @@ -229,4 +229,4 @@ DAMON_RECLAIM再次什么都不做,这样我们就可以退回到基于LRU列 .. [1] https://research.google/pubs/pub48551/ .. [2] https://lwn.net/Articles/787611/ -.. [3] https://www.kernel.org/doc/html/latest/vm/free_page_reporting.html +.. [3] https://www.kernel.org/doc/html/latest/mm/free_page_reporting.html diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst index eee0e8c5c368..aeae2ab65dd8 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst @@ -33,9 +33,9 @@ DAMON 为不同的用户提供了下面这些接口。 口相同。这将在下一个LTS内核发布后被移除,所以用户应该转移到 :ref:`sysfs interface <sysfs_interface>`。 - *内核空间编程接口。* - :doc:`这 </vm/damon/api>` 这是为内核空间程序员准备的。使用它,用户可以通过为你编写内 + :doc:`这 </mm/damon/api>` 这是为内核空间程序员准备的。使用它,用户可以通过为你编写内 核空间的DAMON应用程序,最灵活有效地利用DAMON的每一个功能。你甚至可以为各种地址空间扩展DAMON。 - 详细情况请参考接口 :doc:`文件 </vm/damon/api>`。 + 详细情况请参考接口 :doc:`文件 </mm/damon/api>`。 sysfs接口 ========= @@ -148,7 +148,7 @@ contexts/<N>/monitoring_attrs/ 在 ``nr_regions`` 目录下,有两个文件分别用于DAMON监测区域的下限和上限(``min`` 和 ``max`` ), 这两个文件控制着监测的开销。你可以通过向这些文件的写入和读出来设置和获取这些值。 -关于间隔和监测区域范围的更多细节,请参考设计文件 (:doc:`/vm/damon/design`)。 +关于间隔和监测区域范围的更多细节,请参考设计文件 (:doc:`/mm/damon/design`)。 contexts/<N>/targets/ --------------------- @@ -210,6 +210,8 @@ schemes/<N>/ - ``pageout``: 为具有 ``MADV_PAGEOUT`` 的区域调用 ``madvise()`` 。 - ``hugepage``: 为带有 ``MADV_HUGEPAGE`` 的区域调用 ``madvise()`` 。 - ``nohugepage``: 为带有 ``MADV_NOHUGEPAGE`` 的区域调用 ``madvise()``。 + - ``lru_prio``: 在其LRU列表上对区域进行优先排序。 + - ``lru_deprio``: 对区域的LRU列表进行降低优先处理。 - ``stat``: 什么都不做,只计算统计数据 schemes/<N>/access_pattern/ @@ -318,7 +320,7 @@ DAMON导出了八个文件, ``attrs``, ``target_ids``, ``init_regions``, ---- 用户可以通过读取和写入 ``attrs`` 文件获得和设置 ``采样间隔`` 、 ``聚集间隔`` 、 ``更新间隔`` -以及监测目标区域的最小/最大数量。要详细了解监测属性,请参考 `:doc:/vm/damon/design` 。例如, +以及监测目标区域的最小/最大数量。要详细了解监测属性,请参考 `:doc:/mm/damon/design` 。例如, 下面的命令将这些值设置为5ms、100ms、1000ms、10和1000,然后再次检查:: # cd <debugfs>/damon diff --git a/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst index 6b4988da2c5a..59e51e3539b4 100644 --- a/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst +++ b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst @@ -1,13 +1,6 @@ .. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) -.. - If you want to distribute this text under CC-BY-4.0 only, please use 'The - Linux kernel developers' for author attribution and link this as source: - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst -.. - Note: Only the content of this RST file as found in the Linux kernel sources - is available under CC-BY-4.0, as versions of this text that were processed - (for example by the kernel's build system) might contain content taken from - files which use a more restrictive license. +.. See the bottom of this file for additional redistribution information. + .. include:: ../disclaimer-zh_CN.rst @@ -29,7 +22,9 @@ 请搜索 `LKML内核邮件列表 <https://lore.kernel.org/lkml/>`_ 和 `Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ 存档中匹配的报告并 加入讨论。如果找不到匹配的报告,请安装该系列的最新版本。如果它仍然出现问题, -报告给稳定版邮件列表(stable@vger.kernel.org)。 +请报告给稳定版邮件列表(stable@vger.kernel.org)并抄送回归邮件列表 +(regressions@lists.linux.dev);理想情况下,还可以抄送维护者和相关子系统的 +邮件列表。 在所有其他情况下,请尽可能猜测是哪个内核部分导致了问题。查看MAINTAINERS文件, 了解开发人员希望如何得知问题,大多数情况下,报告问题都是通过电子邮件和抄送 @@ -46,9 +41,10 @@ 有使用附加模块)。还要确保它是在一个正常的环境中构建和运行,并且在问题发生 之前没有被污染(tainted)。 -在编写报告时,要涵盖与问题相关的所有信息,如使用的内核和发行版。在碰见回归时, -尝试给出引入它的更改的提交ID,二分可以找到它。如果您同时面临Linux内核的多个 -问题,请分别报告每个问题。 +当你同时面临Linux内核的多个问题时,请分别报告。在编写报告时,要涵盖与问题 +相关的所有信息,如使用的内核和发行版。如果碰见回归,请把报告抄送回归邮件列表 +(regressions@lists.linux.dev)。也请试试用二分法找出源头;如果成功找到,请 +在报告中写上它的提交ID并抄送sign-off-by链中的所有人。 一旦报告发出,请回答任何出现的问题,并尽可能地提供帮助。这包括通过不时重新 测试新版本并发送状态更新来推动进展。 @@ -156,9 +152,10 @@ 存在问题,因为问题可能已经在那里被修复了。如果您第一次发现供应商内核的问题, 请检查已知最新版本的普通构建是否可以正常运行。 - * 向Linux稳定版邮件列表发送一个简短的问题报告(stable@vger.kernel.org)。大致 - 描述问题,并解释如何复现。讲清楚首个出现问题的版本和最后一个工作正常的版本。 - 然后等待进一步的指示。 + * 向Linux稳定版邮件列表发送一个简短的问题报告(stable@vger.kernel.org)并抄送 + Linux回归邮件列表(regressions@lists.linux.dev);如果你怀疑是由某子系统 + 引起的,请抄送其维护人员和子系统邮件列表。大致描述问题,并解释如何复现。 + 讲清楚首个出现问题的版本和最后一个工作正常的版本。然后等待进一步的指示。 下面的参考章节部分详细解释了这些步骤中的每一步。 @@ -296,17 +293,14 @@ Linus Torvalds和主要的Linux内核开发人员希望看到一些问题尽快 报告过程中有一些“高优先级问题”的处理略有不同。有三种情况符合条件:回归、安全 问题和非常严重的问题。 -如果在旧版本的Linux内核中工作的东西不能在新版本的Linux内核中工作,或者某种 -程度上在新版本的Linux内核中工作得更差,那么你就需要处理“回归”。因此,当一个 -在Linux 5.7中表现良好的WiFi驱动程序在5.8中表现不佳或根本不能工作时,这是一 -种回归。如果应用程序在新的内核中出现不稳定的现象,这也是一种回归,这可能是 -由于内核和用户空间之间的接口(如procfs和sysfs)发生不兼容的更改造成的。显著 -的性能降低或功耗增加也可以称为回归。但是请记住:新内核需要使用与旧内核相似的 -配置来构建(参见下面如何实现这一点)。这是因为内核开发人员在实现新特性时有 -时无法避免不兼容性;但是为了避免回归,这些特性必须在构建配置期间显式地启用。 +如果某个应用程序或实际用例在原先的Linux内核上运行良好,但在使用类似配置编译的 +较新版本上效果更差、或者根本不能用,那么你就需要处理回归问题。 +Documentation/admin-guide/reporting-regressions.rst 对此进行了更详细的解释。 +它还提供了很多你可能想知道的关于回归的其他信息;例如,它解释了如何将您的问题 +添加到回归跟踪列表中,以确保它不会被忽略。 什么是安全问题留给您自己判断。在继续之前,请考虑阅读 -“Documentation/translations/zh_CN/admin-guide/security-bugs.rst”, +Documentation/translations/zh_CN/admin-guide/security-bugs.rst , 因为它提供了如何最恰当地处理安全问题的额外细节。 当发生了完全无法接受的糟糕事情时,此问题就是一个“非常严重的问题”。例如, @@ -390,7 +384,7 @@ Linux内核破坏了它处理的数据或损坏了它运行的硬件。当内核 核未被污染,那么它应该以“Not infected”结束;如果你看到“Tainted:”且后跟一些 空格和字母,那就被污染了。 -如果你的内核被污染了,请阅读“Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst” +如果你的内核被污染了,请阅读 Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst 以找出原因。设法消除污染因素。通常是由以下三种因素之一引起的: 1. 发生了一个可恢复的错误(“kernel Oops”),内核污染了自己,因为内核知道在 @@ -591,7 +585,8 @@ ath10k@lists.infradead.org”,将引导您到ath10k邮件列表的信息页, 搜索引擎,并添加类似“site:lists.infadead.org/pipermail/ath10k/”这 样的搜索条件,这会把结果限制在该链接中的档案。 -也请进一步搜索网络、LKML和bugzilla.kernel.org网站。 +也请进一步搜索网络、LKML和bugzilla.kernel.org网站。如果你的报告需要发送到缺陷 +跟踪器中,那么您可能还需要检查子系统的邮件列表存档,因为可能有人只在那里报告了它。 有关如何搜索以及在找到匹配报告时如何操作的详细信息,请参阅上面的“搜索现有报告 (第一部分)”。 @@ -802,10 +797,10 @@ Linux 首席开发者 Linus Torvalds 认为 Linux 内核永远不应恶化,这 重现它。 有一个叫做“二分”的过程可以来寻找变化,这在 -“Documentation/translations/zh_CN/admin-guide/bug-bisect.rst”文档中进行了详细 +Documentation/translations/zh_CN/admin-guide/bug-bisect.rst 文档中进行了详细 的描述,这个过程通常需要你构建十到二十个内核镜像,每次都尝试在构建下一个镜像 之前重现问题。是的,这需要花费一些时间,但不用担心,它比大多数人想象的要快得多。 -多亏了“binary search二进制搜索”,这将引导你在源代码管理系统中找到导致回归的提交。 +多亏了“binary search二分搜索”,这将引导你在源代码管理系统中找到导致回归的提交。 一旦你找到它,就在网上搜索其主题、提交ID和缩短的提交ID(提交ID的前12个字符)。 如果有的话,这将引导您找到关于它的现有报告。 @@ -823,10 +818,10 @@ Linux 首席开发者 Linus Torvalds 认为 Linux 内核永远不应恶化,这 当处理回归问题时,请确保你所面临的问题真的是由内核引起的,而不是由其他东西 引起的,如上文所述。 -在整个过程中,请记住:只有当旧内核和新内核的配置相似时,问题才算回归。最好 -的方法是:把配置文件(``.config``)从旧的工作内核直接复制到你尝试的每个新内 -核版本。之后运行 ``make oldnoconfig`` 来调整它以适应新版本的需要,而不启用 -任何新的功能,因为那些功能也可能导致回归。 +在整个过程中,请记住:只有当旧内核和新内核的配置相似时,问题才算回归。这可以 +通过 ``make olddefconfig`` 来实现,详细解释参见 +Documentation/admin-guide/reporting-regressions.rst ;它还提供了大量其他您 +可能希望了解的有关回归的信息。 撰写并发送报告 @@ -959,11 +954,19 @@ Linux 首席开发者 Linus Torvalds 认为 Linux 内核永远不应恶化,这 **非常严重的缺陷** :确保在主题或工单标题以及第一段中明显标出 severeness (非常严重的)。 -**回归** :如果问题是一个回归,请在邮件的主题或缺陷跟踪器的标题中添加 -[REGRESSION]。如果您没有进行二分,请至少注明您测试的最新主线版本(比如 5.7) -和出现问题的最新版本(比如 5.8)。如果您成功地进行了二分,请注明导致回归 -的提交ID和主题。也请添加该变更的作者到你的报告中;如果您需要将您的缺陷提交 -到缺陷跟踪器中,请将报告以私人邮件的形式转发给他,并注明报告提交地点。 +**回归** :报告的主题应以“[REGRESSION]”开头。 + +如果您成功用二分法定位了问题,请使用引入回归之更改的标题作为主题的第二部分。 +请在报告中写明“罪魁祸首”的提交ID。如果未能成功二分,请在报告中讲明最后一个 +正常工作的版本(例如5.7)和最先发生问题的版本(例如5.8-rc1)。 + +通过邮件发送报告时,请抄送Linux回归邮件列表(regressions@lists.linux.dev)。 +如果报告需要提交到某个web追踪器,请继续提交;并在提交后,通过邮件将报告转发 +至回归列表;抄送相关子系统的维护人员和邮件列表。请确保报告是内联转发的,不要 +把它作为附件。另外请在顶部添加一个简短的说明,在那里写上工单的网址。 + +在邮寄或转发报告时,如果成功二分,需要将“罪魁祸首”的作者添加到收件人中;同时 +抄送signed-off-by链中的每个人,您可以在提交消息的末尾找到。 **安全问题** :对于这种问题,你将必须评估:如果细节被公开披露,是否会对其他 用户产生短期风险。如果不会,只需按照所述继续报告问题。如果有此风险,你需要 @@ -980,7 +983,7 @@ Linux 首席开发者 Linus Torvalds 认为 Linux 内核永远不应恶化,这 报告,请将报告的文本转发到这些地址;但请在报告的顶部加上注释,表明您提交了 报告,并附上工单链接。 -更多信息请参见“Documentation/translations/zh_CN/admin-guide/security-bugs.rst”。 +更多信息请参见 Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。 发布报告后的责任 @@ -1173,14 +1176,18 @@ FLOSS 问题报告的人看,询问他们的意见。同时征求他们关于 报告回归 ~~~~~~~~~~ - *向Linux稳定版邮件列表发送一个简短的问题报告(stable@vger.kernel.org)。 - 大致描述问题,并解释如何复现。讲清楚首个出现问题的版本和最后一个工作正常 - 的版本。然后等待进一步的指示。* + *向Linux稳定版邮件列表发送一个简短的问题报告(stable@vger.kernel.org)并 + 抄送Linux回归邮件列表(regressions@lists.linux.dev);如果你怀疑是由某 + 子系统引起的,请抄送其维护人员和子系统邮件列表。大致描述问题,并解释如 + 何复现。讲清楚首个出现问题的版本和最后一个工作正常的版本。然后等待进一 + 步的指示。* 当报告在稳定版或长期支持内核线内发生的回归(例如在从5.10.4更新到5.10.5时), -一份简短的报告足以快速报告问题。因此只需要粗略的描述。 +一份简短的报告足以快速报告问题。因此只需向稳定版和回归邮件列表发送粗略的描述; +不过如果你怀疑某子系统导致此问题的话,请一并抄送其维护人员和子系统邮件列表, +这会加快进程。 -但是请注意,如果您能够指明引入问题的确切版本,这将对开发人员有很大帮助。因此 +请注意,如果您能够指明引入问题的确切版本,这将对开发人员有很大帮助。因此 如果有时间的话,请尝试使用普通内核找到该版本。让我们假设发行版发布Linux内核 5.10.5到5.10.8的更新时发生了故障。那么按照上面的指示,去检查该版本线中的最新 内核,比如5.10.9。如果问题出现,请尝试普通5.10.5,以确保供应商应用的补丁不会 @@ -1190,7 +1197,9 @@ FLOSS 问题报告的人看,询问他们的意见。同时征求他们关于 前一段基本粗略地概述了“二分”方法。一旦报告出来,您可能会被要求做一个正确的 报告,因为它允许精确地定位导致问题的确切更改(然后很容易被恢复以快速修复问题)。 因此如果时间允许,考虑立即进行适当的二分。有关如何详细信息,请参阅“对回归的 -特别关照”部分和文档“Documentation/translations/zh_CN/admin-guide/bug-bisect.rst”。 +特别关照”部分和文档 Documentation/translations/zh_CN/admin-guide/bug-bisect.rst 。 +如果成功二分的话,请将“罪魁祸首”的作者添加到收件人中;同时抄送所有在 +signed-off-by链中的人,您可以在提交消息的末尾找到。 “报告仅在旧内核版本线中发生的问题”的参考 @@ -1207,7 +1216,7 @@ FLOSS 问题报告的人看,询问他们的意见。同时征求他们关于 即使是微小的、看似明显的代码变化,有时也会带来新的、完全意想不到的问题。稳 定版和长期支持内核的维护者非常清楚这一点,因此他们只对这些内核进行符合 -“Documentation/translations/zh_CN/process/stable-kernel-rules.rst”中所列出的 +Documentation/translations/zh_CN/process/stable-kernel-rules.rst 中所列出的 规则的修改。 复杂或有风险的修改不符合条件,因此只能应用于主线。其他的修复很容易被回溯到 @@ -1333,3 +1342,27 @@ FLOSS 问题报告的人看,询问他们的意见。同时征求他们关于 向 Linux 内核开发者报告问题是很难的:这个文档的长度和复杂性以及字里行间的内 涵都说明了这一点。但目前就是这样了。这篇文字的主要作者希望通过记录现状来为 以后改善这种状况打下一些基础。 + + +.. + end-of-content +.. + This English version of this document is maintained by Thorsten Leemhuis + <linux@leemhuis.info>. If you spot a typo or small mistake, feel free to + let him know directly and he'll fix it. For translation problems, please + contact with translators. You are free to do the same in a mostly informal + way if you want to contribute changes to the text, but for copyright + reasons please CC linux-doc@vger.kernel.org and "sign-off" your + contribution as Documentation/process/submitting-patches.rst outlines in + the section "Sign your work - the Developer's Certificate of Origin". +.. + This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top + of the file. If you want to distribute this text under CC-BY-4.0 only, + please use "The Linux kernel developers" for author attribution and link + this as source: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst +.. + Note: Only the content of this RST file as found in the Linux kernel sources + is available under CC-BY-4.0, as versions of this text that were processed + (for example by the kernel's build system) might contain content taken from + files which use a more restrictive license. diff --git a/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst b/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst new file mode 100644 index 000000000000..c0461ee855bc --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst @@ -0,0 +1,370 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) +.. 【重分发信息参见本文件结尾】 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/reporting-regressions.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + + +============ +报告回归问题 +============ + +“*我们拒绝出现回归*”是Linux内核开发的首要规则;Linux的发起者和领军开发者Linus +Torvalds立下了此规则并确保它被落实。 + +本文档描述了这条规则对用户的意义,以及Linux内核开发模型如何确保解决所有被报告 +的回归;关于内核开发者如何处理的方面参见 Documentation/process/handling-regressions.rst 。 + + +本文重点(亦即“太长不看”) +========================== + +#. 如果某程序在原先的Linux内核上运行良好,但在较新版本上效果更差、或者根本不 + 能用,那么你就碰见回归问题了。注意,新内核需要使用类似配置编译;更多相关细 + 节参见下方。 + +#. 按照 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst 中 + 所说的报告你的问题,该文档已经包含了所有关于回归的重要方面,为了方便起见也 + 复制到了下面。两个重点:在报告主题中使用“[REGRESSION]”开头并抄送或转发到 + `回归邮件列表 <https://lore.kernel.org/regressions/>`_ + (regressions@lists.linux.dev)。 + +#. 可选但是建议:在发送或转发报告时,指明该回归发生的起点,以便Linux内核回归 + 追踪机器人“regzbot”可以追踪此问题:: + + #regzbot introduced v5.13..v5.14-rc1 + + +与用户相关的所有Linux内核回归细节 +================================= + + +基本重点 +-------- + + +什么是“回归”以及什么是“无回归规则”? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +如果某程序/实例在原先的Linux内核上运行良好,但在较新版本上效果更差、或者根本 +不能用,那么你就碰见回归问题了。“无回归规则”不允许出现这种情况。如果偶然发 +生了,导致问题的开发者应当迅速修复问题。 + +也就是说,若Linux 5.13中的WiFi驱动程序运行良好,但是在5.14版本上却不能用、速 +度明显变慢或出现错误,那就出现了回归。如果某正常工作的应用程序突然在新内核上 +出现不稳定,这也是回归;这些问题可能是由于procfs、sysfs或Linux提供给用户空间 +软件的许多其他接口之一的变化。但请记住,前述例子中的5.14需要使用类似于5.13的 +配置构建。这可以用 ``make olddefconfig`` 实现,详细解释见下。 + +注意本节第一句话中的“实例”:即使开发者需要遵循“无回归”规则,但仍可自由地改 +变内核的任何方面,甚至是导出到用户空间的API或ABI,只要别破坏现有的应用程序或 +用例。 + +还需注意,“无回归”规则只限制内核提供给用户空间的接口。它不适用于内核内部接 +口,比如一些外部开发的驱动程序用来插入钩子到内核的模块API。 + +如何报告回归? +~~~~~~~~~~~~~~ + +只需按照 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst 中 +所说的报告你的问题,该文档已经包含了要点。下面几点概述了一下只在回归中重要的 +方面: + + * 在检查可加入讨论的现有报告时,别忘了搜索 `Linux回归邮件列表 + <https://lore.kernel.org/regressions/>`_ 和 `regzbot网页界面 + <https://linux-regtracking.leemhuis.info/regzbot/>`_ 。 + + * 在报告主题的开头加上“[REGRESSION]”。 + + * 在你的报告中明确最后一个正常工作的内核版本和首个出问题的版本。如若可能, + 用二分法尝试找出导致回归的变更,更多细节见下。 + + * 记得把报告发到Linux回归邮件列表(regressions@lists.linux.dev)。 + + * 如果通过邮件报告回归,请抄送回归列表。 + + * 如果你使用某些缺陷追踪器报告回归,请通过邮件转发已提交的报告到回归列表, + 并抄送维护者以及出问题的相关子系统的邮件列表。 + + 如果是稳定版或长期支持版系列(如v5.15.3…v5.15.5)的回归,请记得抄送 + `Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ (stable@vger.kernel.org)。 + + 如果你成功地执行了二分,请抄送肇事提交的信息中所有签了“Signed-off-by:”的人。 + +在抄送你的报告到列表时,也请记得通知前述的Linux内核回归追踪机器人。只需在邮件 +中包含如下片段:: + + #regzbot introduced: v5.13..v5.14-rc1 + +Regzbot会就将你的邮件视为在某个特定版本区间的回归报告。上例中即linux v5.13仍 +然正常,而Linux 5.14-rc1是首个您遇到问题的版本。如果你执行了二分以查找导致回 +归的提交,请使用指定肇事提交的id代替:: + + #regzbot introduced: 1f2e3d4c5d + +添加这样的“regzbot命令”对你是有好处的,它会确保报告不会被忽略。如果你省略了 +它,Linux内核的回归跟踪者会把你的回归告诉regzbot,只要你发送了一个副本到回归 +邮件列表。但是回归跟踪者只有一个人,有时不得不休息或甚至偶尔享受可以远离电脑 +的时光(听起来很疯狂)。因此,依赖此人手动将回归添加到 `已追踪且尚未解决的 +Linux内核回归列表 <https://linux-regtracking.leemhuis.info/regzbot/>`_ 和 +regzbot发送的每周回归报告,可能会出现延迟。 这样的延误会导致Linus Torvalds +在决定“继续开发还是发布新版本?”时忽略严重的回归。 + +真的修复了所有的回归吗? +~~~~~~~~~~~~~~~~~~~~~~~~ + +几乎所有都是,只要引起问题的变更(肇事提交)被可靠定位。也有些回归可以不用这 +样,但通常是必须的。 + +谁需要找出回归的根本原因? +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +受影响代码区域的开发者应该自行尝试定位问题所在。但仅靠他们的努力往往是不可 +能做到的,很多问题只发生在开发者的无法接触的其他特定外部环境中——例如特定的 +硬件平台、固件、Linux发行版、系统的配置或应用程序。这就是为什么最终往往是报 +告者定位肇事提交;有时用户甚至需要再运行额外测试以查明确切的根本原因。开发 +者应该提供建议和可能的帮助,以使普通用户更容易完成该流程。 + +如何找到罪魁祸首? +~~~~~~~~~~~~~~~~~~ + +如 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst (简要) +和 Documentation/translations/zh_CN/admin-guide/bug-bisect.rst (详细)中所 +述,执行二分。听起来工作量很大,但大部分情况下很快就能找到罪魁祸首。如果这很 +困难或可靠地重现问题很耗时,请考虑与其他受影响的用户合作,一起缩小搜索范围。 + +当出现回归时我可以向谁寻求建议? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +发送邮件到回归邮件列表(regressions@lists.linux.dev)同时抄送Linux内核的回归 +跟踪者(regressions@leemhuis.info);如果问题需要保密处理,可以省略列表。 + + +关于回归的更多细节 +------------------ + + +“无回归规则”的目标是什么? +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +用户应该放心升级内核版本,而不必担心有程序可能崩溃。这符合内核开发者的利益, +可以使更新有吸引力:他们不希望用户停留在停止维护或超过一年半的稳定/长期Linux +版本系列上。这也符合所有人的利益,因为 `那些系列可能含有已知的缺陷、安全问题 +或其他后续版本已经修复的问题 +<http://www.kroah.com/log/blog/2018/08/24/what-stable-kernel-should-i-use/>`_ 。 +此外,内核开发者希望使用户测试最新的预发行版或常规发行版变得简单而有吸引力。 +这同样符合所有人的利益,如果新版本出来后很快就有相关报告,会使追踪和修复问题 +更容易。 + +实际中“无回归”规则真的可行吗? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +这不是句玩笑话,请见Linux创建者和主要开发人员Linus Torvalds在邮件列表中的许 +多发言,其中一些在 Documentation/process/handling-regressions.rst 中被引用。 + +此规则的例外情况极为罕见;之前当开发者认为某个特定的情况有必要援引例外时, +基本都被证明错了。 + +谁来确保“无回归”被落实? +~~~~~~~~~~~~~~~~~~~~~~~~ + +照看和支撑树的子系统维护者应该关心这一点——例如,Linus Torvalds之于主线, +Greg Kroah-Hartman等人之于各种稳定/长期系列。 + +他们都得到了别人的帮助,以确保回归报告不会被遗漏。其中之一是Thorsten +Leemhuis,他目前担任Linux内核的“回归跟踪者”;为了做好这项工作,他使用了 +regzbot——Linux内核回归跟踪机器人。所以这就是为什么要抄送或转发你的报告到 +回归邮件列表来通知这些人,已经最好在你的邮件中包含“regzbot命令”来立即追踪它。 + +回归通常多久能修复? +~~~~~~~~~~~~~~~~~~~~ + +开发者应该尽快修复任何被报告的回归,以提供及时为受影响的用户提供解决方案,并 +防止更多用户遇到问题;然而,开发人员需要花足够的时间和注意力确保回归修复不会 +造成额外的损害。 + +因此,答案取决于各种因素,如回归的影响、存在时长或出现于哪个Linux版本系列。 +但最终,大多数的回归应该在两周内修复。 + +当问题可以通过升级某些软件解决时,是回归吗? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +基本都是。如果开发人员告诉您其他情况,请咨询上述回归跟踪者。 + +当新内核变慢或能耗增加,是回归吗? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +是的,但有一些差别。在微型基准测试中变慢5%不太可能被视为回归,除非它也会对 +广泛基准测试的结果产生超过1%的影响。如果有疑问,请寻求建议。 + +当更新Linux时外部内核模块崩溃了,是回归吗? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +不,因为“无回归”规则仅限于Linux内核提供给用户空间的接口和服务。因此,它不包括 +构建或运行外部开发的内核模块,因为它们在内核空间中运行与挂进内核使用的内部接 +口偶尔会变化。 + +如何处理安全修复引起的回归? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在极为罕见的情况下,安全问题无法在不引起回归的情况下修复;这些修复都被放弃了, +因为它们终究会引起问题。幸运的是这种两难境地基本都可以避免,受影响区域的主要 +开发者以及Linus Torvalds本人通常都会努力在不引入回归的情况下解决安全问题。 + +如果你仍然面临此种情况,请查看邮件列表档案是否有人尽力避免过回归。如果没有, +请报告它;如有疑问,请如上所述寻求建议。 + +当修复回归时不可避免会引入另一个,如何处理? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +很遗憾这种事确实会出现,但幸运的是并不经常出现;如果发生了,受影响代码区的资 +深开发者应当调查该问题以找到避免回归的解决方法,至少避免它们的影响。如果你遇 +到这样的情况,如上所述:检查之前的讨论是否有人已经尽了最大努力,如有疑问请寻 +求建议。 + +小提示:如果人们在每个开发周期中定期给出主线预发布(即v5.15-rc1或-rc3)以供 +测试,则可以避免这种情况。为了更好地解释,可以设想一个在Linux v5.14和v5.15-rc1 +之间集成的更改,该更改导致了回归,但同时是应用于5.15-rc1的其他改进的强依赖。 +如果有人在5.15发布之前就发现并报告了这个问题,那么所有更改都可以直接撤销,从 +而解决回归问题。而就在几天或几周后,此解决方案变成了不可能,因为一些软件可能 +已经开始依赖于后续更改之一:撤销所有更改将导致上述用户软件出现回归,这是不可 +接受的。 + +若我所依赖的功能在数月前被移除了,是回归吗? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +是的,但如前节所述,通常很难修复此类回归。因此需要逐案处理。这也是定期测试主 +线预发布对所有人有好处的另一个原因。 + +如果我似乎是唯一受影响的人,是否仍适用“无回归”规则? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +适用,但仅限于实际使用:Linux开发人员希望能够自由地取消那些只能在阁楼和博物 +馆中找到的硬件的支持。 + +请注意,有时为了取得进展,不得不出现回归——后者也是防止Linux停滞不前所必需 +的。因此如果回归所影响的用户很少,那么为了他们和其他人更大的利益,还是让事情 +过去吧。尤其是存在某种规避回归的简单方法,例如更新一些软件或者使用专门为此目 +的创建的内核参数。 + +回归规则是否也适用于staging树中的代码? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +不,参见 `适用于所有staging代码配置选项的帮助文本 +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/staging/Kconfig>`_ , +其早已声明:: + + 请注意:这些驱动正在积极开发中,可能无法正常工作,并可能包含会在不久的 + 将来发生变化的用户接口。 + +虽然staging开发人员通常坚持“无回归”的原则,但有时为了取得进展也会违背它。这就 +是为什么当staging树的WiFi驱动被基本推倒重来时,有些用户不得不处理回归(通常可 +以忽略)。 + +为什么较新版本必须“使用相似配置编译”? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +因为Linux内核开发人员有时会集成已知的会导致回归的变更,但使它们成为可选的,并 +在内核的默认配置下禁用它们。这一技巧允许进步,否则“无回归”规则将导致停滞。 + +例如,试想一个新的可以阻止恶意软件滥用某个内核的接口的安全特性,同时又需要满足 +另一个很罕见的应用程序。上述的方法可使两方都满意:使用这些应用程序的人可以关闭 +新的安全功能,而其他不会遇到麻烦的人可以启用它。 + +如何创建与旧内核相似的配置? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +用一个已知良好的内核启动机器,并用 ``make olddefconfig`` 配置新版的Linux。这 +会让内核的构建脚本从正在运行的内核中摘录配置文件(“.config”文件),作为即将编 +译的新版本的基础配置;同时将所有新的配置选项设为默认值,以禁用可能导致回归的 +新功能。 + +如何报告在预编译的普通内核中发现的回归? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +您需要确保新的内核是用与旧版相似的配置编译(见上文),因为那些构建它们的人可 +能启用了一些已知的与新内核不兼容的特性。如有疑问,请向内核的提供者报告问题并 +寻求建议。 + + +用“regzbot”追踪回归的更多信息 +----------------------------- + +什么是回归追踪?为啥我需要关心它? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +像“无回归”这样的规则需要有人来确保它们被遵守,否则会被有意/无意打破。历史证 +明了这一点对于Linux内核开发也适用。这就是为什么Linux内核的回归跟踪者Thorsten +Leemhuis,,和另一些人尽力关注所有的回归直到他们解决。他们从未为此获得报酬, +因此这项工作是在尽最大努力的基础上完成的。 + +为什么/如何使用机器人追踪Linux内核回归? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +由于Linux内核开发过程的分布式和松散结构,完全手动跟踪回归已经被证明是相当困难 +的。因此Linux内核的回归跟踪者开发了regzbot来促进这项工作,其长期目标是尽可能为 +所有相关人员自动化回归跟踪。 + +Regzbot通过监视跟踪的回归报告的回复来工作。此外,它还查找用“Link:”标签引用这 +些报告的补丁;对这些补丁的回复也会被跟踪。结合这些数据,可以很好地了解当前修 +复过程的状态。 + +如何查看regzbot当前追踪的回归? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +参见 `regzbot在线 <https://linux-regtracking.leemhuis.info/regzbot/>`_ 。 + +何种问题可以由regzbot追踪? +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +该机器人只为了跟踪回归,因此请不要让regzbot涉及常规问题。但是对于Linux内核的 +回归跟踪者来说,让regzbot跟踪严重问题也可以,如有关挂起、损坏数据或内部错误 +(Panic、Oops、BUG()、warning…)的报告。 + +如何修改被追踪回归的相关信息? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在直接或间接回复报告邮件时使用“regzbot命令”即可。最简单的方法是:在“已发送”文 +件夹或邮件列表存档中找到报告,然后使用邮件客户端的“全部回复”功能对其进行回复。 +在该邮件中的独立段落中可使用以下命令之一(即使用空行将这些命令中的一个或多个与 +其余邮件文本分隔开)。 + + * 更新回归引入起点,例如在执行二分之后:: + + #regzbot introduced: 1f2e3d4c5d + + * 设置或更新标题:: + + #regzbot title: foo + + * 监视讨论或bugzilla.kernel.org上有关讨论或修复的工单:: + + #regzbot monitor: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + #regzbot monitor: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * 标记一个有更多相关细节的地方,例如有关但主题不同的邮件列表帖子或缺陷追踪器中的工单:: + + #regzbot link: https://bugzilla.kernel.org/show_bug.cgi?id=123456789 + + * 标记回归已失效:: + + #regzbot invalid: wasn't a regression, problem has always existed + +Regzbot还支持其他一些主要由开发人员或回归追踪人员使用的命令。命令的更多细节请 +参考 `入门指南 <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/getting_started.md>`_ +和 `参考手册 <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md>`_ 。 + +.. + 正文结束 +.. + 如本文件开头所述,本文以GPL-2.0+或CC-BY-4.0许可发行。如您想仅在CC-BY-4.0许 + 可下重分发本文,请用“Linux内核开发者”作为作者,并用如下链接作为来源: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst +.. + 注意:本RST文件内容只有在来自Linux内核源代码时是使用CC-BY-4.0许可的,因为经 + 过处理的版本(如经内核的构建系统)可能包含来自使用更严格许可证的文件的内容。 |