R 中的错误报告

本文档说明了在 R 项目中发现错误或有要提交的补丁时该怎么做。它涵盖

  1. 确保你的问题是一个错误；
  2. 提交错误报告的位置（请参阅垃圾邮件保护注意！）
  3. 如何编写有用且有成效的错误报告；
  4. 如何提交补丁；
  5. 如果出现问题该怎么办。

目的是通过确保错误报告清晰明了，便于开发者响应，充分利用你的时间和 R 开发者的时间。

确保这是一个错误

在某些情况下，某些事情肯定是一个错误；其中一个例子是当 R 会话意外终止或段错误时。这看起来像

    *** caught segfault ***
address (nil), cause 'memory not mapped'

如果你看到这样的错误，除非你已经编写了自己的编译代码或内部函数调用（例如，通过.C或.Internal），那么它肯定是一个错误1。

其他明显的错误示例是代码没有按照文档说明执行的情况：要么代码错误，要么文档错误。无论哪种方式，都需要修复一些东西。

代码执行意外操作不一定是错误 - 务必仔细查看所调用函数的文档，以查看它表现出的行为是否符合其设计目的，即使它不是你想要的。同样，看似相同的数字不相等的问题是已知、已记录且难以解决的问题 - 而不是错误。

在所有情况下，如果你认为它可能是一个错误，请尝试使用--vanilla选项从命令行启动 R，以确保这是一个干净的会话，然后查看错误是否仍然出现。将你的代码减少到运行错误发生的函数调用所需的最小值，特别是只附加该调用所需的包（如果有）。

如果你没有错误，而是对 R 中的新功能有建议，你可以将其提交到提交错误的位置，请参阅下一部分。

如果你的问题不属于任何这些类别 - 例如，R 运行速度比预期慢，或者某些内容可以工作，但未按你认为最好的方式定义，你应该咨询某人。如果你不认识任何可以查看你的代码并查看是否可以加速它的人，或者其他函数是否更适合你的需求，那么可以寻求帮助的一些有用地方是

  1. r-help 邮件列表；或 其他 R 邮件列表。
  2. Bioconductor 支持网站.
  3. StackOverflow 的 R 部分.
  4. R 互联网中继聊天 (IRC) 频道.

提交错误报告和补丁的位置

如果您的问题肯定是一个错误 - 要么因为它属于上述错误类别之一，要么是因为您已经向人们寻求帮助，并且他们已经确认这是一个问题 - 那么现在是提交报告以便修复它的时候了。

根据问题，您可能需要在不同的地方提交错误报告。第一步是查看带有错误的函数来自哪个包。R Core 团队仅维护核心语言和标记为 Maintainer: R Core Team <[email protected]> 的 R 包。您可以通过在 R 中运行例如 maintainer("graphics") 来查看此标签。
但是请注意：不要向 R-core 发送有关错误等的电子邮件，甚至不要发送安全漏洞！！

如果您的错误在 somePkg 中，并且该错误不是由 R Core 团队维护的，则应将报告提交给包维护者。运行 bug.report(package = "somePkg") 会将您引导至正确的位置，要么打开相关的错误跟踪网页，要么帮助您撰写电子邮件给包维护者。

bug.report 函数在某些 IDE（例如 RStudio）中被禁用，以避免误用；要自己识别提交报告的正确位置，首先查看 packageDescription("somePkg") 的输出、包的 R 帮助或来自相关存储库的包的网页，例如 CRAN 或 Bioconductor。一些包有一个错误提交页面，例如在包描述中的 BugReports 字段下列出的 GitHub 上的 issue tracker。如果您按照此链接，您可能会发现您的错误已被报告，否则您可以在那里提交您的报告，按照下面讨论的错误报告指南进行操作。如果没有错误提交页面，您应该通过包描述中的地址将您的错误报告通过电子邮件发送给包 Maintainer。

但是，如果您的错误在语言或 Core 支持的包中，您应该将您的报告提交给 R 的 Bugzilla。
注意：由于垃圾邮件发送者滥用，自 2016-07-09 起，只有“成员”（包括所有之前提交过错误的人）才能在 R 的 Bugzilla 上提交新的错误。要获取一个 Bugzilla 帐户（即成为“成员”），请向 [email protected] 发送一封电子邮件（从您希望用作登录名的地址发送），简要说明原因，一名志愿者会将您添加到 R 的 Bugzilla 成员中。确保报告不无关紧要非常重要。最简单的方法是首先查看 R 中即将进行的更改，以查看错误是否已得到修补（只是尚未发布），以及 浏览最新的错误报告 或 在 Bugzilla 中搜索错误，以查看（即使尚未修补）是否已报告该错误。如果您的错误尚未报告或修复，您可以按照 编写一份好的错误报告 一节中的指南报告该错误。如果您有随附错误的修补程序，请参阅 如何提交修补程序 一节。

默认情况下，提交给 R 的 Bugzilla 的报告是公开的。如果您认为您的错误是安全漏洞，不应公开，您可以在错误提交页面上选择“显示高级字段”，向下滚动到页面底部，并选中仅允许 R-security 组的成员查看该错误。在选中此标记之前，最好确保该漏洞确实对安全敏感，利用它会允许攻击者执行无法使用来自相同上下文的标准 R 功能执行的代码。请注意，system()、system2()、dyn.load() 可以通过设计用于执行任意代码。

如果您希望提交功能请求，而不是错误报告，最好的办法是先在 r-devel 邮件列表上询问。如果反馈是正面的，您可以使用 Bugzilla 上的错误报告表单提交您的建议，您应该在 Component 字段中选择 Wishlist，并在摘要开头加上 Wishlist:。

与消息翻译相关的问题应发送给最后一位翻译人员或相关的 翻译团队。要查找最后一位翻译人员，您需要查看 R 源代码中相关 .po 文件顶部的注释，例如基本包中消息的德语翻译位于 src/library/base/po/R-de.po 中。您可以从 CRAN 下载 R 源代码，或 浏览 R-devel 源代码 或 在 GitHub 上查看其镜像。

撰写一份好的错误报告

错误报告应包括 重现 错误的方法。这应该尽可能简单。如果尝试修复错误的人无法弄清楚如何使其出现，或者必须经过许多不必要的步骤才能使其出现，您将浪费他们大量时间。

Bugzilla 由少数人维护，因此最好确保您的错误报告清晰且撰写得当。如果不是这样，它将从维护人员那里吸取更多精力，并且错误修复需要更长的时间 - 或者它最终可能根本无法得到处理。特别是，您应该

  1. 为错误编写一个清晰且唯一的摘要。“停止运行 lm() 会导致崩溃”很好；“软件崩溃”则不行。
  2. 在描述中，包括上述重现错误的步骤。
  3. 识别发生了什么（“软件崩溃”）以及您期望发生什么（“lm() 应该停止运行”）。
  4. 识别您发现此错误的平台、架构和 R 版本。您可以通过键入 R.version 从 R 中检索该信息。
  5. 只关注发生的事情的事实，而不是您对错误是什么以及它来自何处的理论。

在这一点上，您已经写了一份好的错误报告！坐下来等待开发人员对此做出回应。如果您在该响应中遇到任何问题，请参阅部分 如果有问题该怎么办。

如何提交补丁

有时您会发现一个错误，并且还可以通过查看代码了解如何修复它。当这种情况发生时，您有机会提交补丁，这可以减少 R 开发人员的工作量：他们可以测试、调整和包含代码，而不是必须从头开始编写所有代码。

要准备补丁，您需要 R 的最新开发人员版本。这是在 Subversion (SVN) 存储库中维护的。一旦在您的系统上安装了 SVN，请打开命令行并键入

svn checkout https://svn.r-project.org/R/trunk/ R-devel

这应该在您当前的工作目录中创建一个目录 R-devel。其中包含最新版 R 的源代码。

进行并进行您需要进行的更改以修补错误 - 尽量坚持您正在更改的函数使用的任何编码风格和约定，以便让事情变得更容易。完成后，转到终端中的 R-devel 目录并键入

svn update
svn diff > patch.diff

这会更新代码，然后创建一个新文件 patch.diff，其中包含 R 的最新版本与您的更改之间的差异。这就是补丁！在提交补丁之前，请通过运行确保构建系统正常工作

make check-devel

阅读输出，并查找注释、警告和错误。最后，将补丁附加到您正在编写的错误报告中，在报告中注明有一个关联的补丁，然后您就完成了。

如果出现问题该怎么办

在理想世界中，您编写一份内容丰富的错误报告（也许提交一个补丁），有人会立即出现并修复它，每个人都会很高兴。在我们所处的世界中，维护 R 的人员有很多责任，而且他们都是作为志愿者来完成这项工作的。这意味着，实际上，错误可能需要很长时间才能得到修复，或者意外地被遗漏，或者导致意外或令人不快的结果——这并不是出于任何恶意，而是因为负责该软件的人员可能会感到非常紧张。

如果您遇到 R 的 Bugzilla 的技术问题，并且一段时间后仍无法自行解决，您应该联系当前维护人员：[email protected]。如果您觉得您的错误被遗漏了（例如，因为 R 的新版本已经发布，但它没有得到修复），您可以通过在 Bugzilla 上简单地添加一条评论（如“这仍然存在于 x.y.z 版本中”）来引起人们的注意。更好的办法是安装一个预发布的 alpha 或 beta 版本以确认它仍然存在，并报告该问题。

如果您认为它被错误评估了，您可以在 Bugzilla 上就此留下评论。如果您与 R Core 的成员有个人交往，您可以直接联系他们。在任何一种情况下，都要清楚地说明您的情况，并尊重 R Core 成员可能与您不同地判断问题的严重性（甚至是否是一个错误）这一事实。

  1. 如果您要调用已编译的代码，请检查您是否因使用错误的参数类型（模式）而导致 R 崩溃。↩︎

© R 基金会。有关此网站的疑问，请联系 ；有关 R 本身的疑问，请参阅 获取帮助 部分。