---

D.2.3 如何报告错误¶

请将Octave的错误报告提交到Octave错误跟踪器 https://bugs.octave.org。

有效报告错误的基本原则是： 报告所有事实。如果你不确定某个事实是该说还是不该说，那就说出来！

人们常常省略事实，因为他们自认为知道问题的原因，并断定某些细节无关紧要。比如，你可能会假设在示例中使用的变量名无关紧要。确实，很可能真的无关紧要，但没人能百分之百确定。也许这个错误是一个野内存引用，恰好从存储该变量名的内存位置读取了数据；也许如果变量名不同，该内存位置的内容就会在存在错误的情况下误导解释器做出正确的行为。稳妥起见，请给出一个具体、完整的示例。

请记住，错误报告的目的是让其他人能够修复一个尚不为人知的错误。因此，编写错误报告时请始终假定该错误是未知的。

有时人们只给出一些粗略的事实，然后问："这有没有让你想起什么？" 这对我们修复错误毫无帮助。最好一开始就发送一份完整的错误报告。

尽量让你的错误报告内容完整、自包含。如果我们不得不向你索取更多信息，你在回复时最好附上之前提供的全部信息以及缺失的部分。

为了便于他人调查该错误，你应当提供以下所有内容：

• Octave的版本。你可以通过查看Octave启动时打印的版本号来获取，或使用-v选项运行来获取。
• 一个能够重现该错误的完整输入文件。

  单条语句可能不足以构成完整的示例——错误可能依赖于该最终出错语句中未曾体现的其他细节。

• 你为执行该示例并观察错误而提供给Octave的命令参数。为确保不会遗漏重要信息，请列出所有选项。

  如果我们去猜测参数，很可能猜错，从而无法复现该错误。

• 你使用的机器类型，以及操作系统的名称和版本号。
• 你在安装解释器时提供给configure命令的命令行参数。
• 你对解释器源代码所做的任何修改的完整列表。

  请精确描述这些修改——为它们提供上下文差异（context diff）。

• 与标准Octave安装流程有任何偏离的详细说明。
• 对你观察到的、你认为不正确的行为进行描述。例如："解释器收到致命信号"，或"第208行产生的输出不正确"。

  当然，如果错误是解释器收到致命信号，你不可能注意不到。但如果错误是输出不正确，除非明显有误，否则我们可能不会注意到。

  即使你遇到的问题确实是致命信号，你也应该明确说出来。假设发生了一些奇怪的情况，比如你的解释器副本不同步了，或者你遇到了系统C库中的错误。你的副本可能会崩溃，但我们这里的副本不会。如果你说明了预期会崩溃，那么当我们这里的解释器没有崩溃时，我们就知道错误没有复现。如果你没有说明预期会崩溃，那么我们就不知道错误是否正在发生，也无法从观察中得出任何结论。

  通常观察到的症状是程序运行时的输出不正确。遗憾的是，除非程序简短且简单，否则这不足以提供足够的信息。如果你能解释预期的输出是什么，以及为什么实际输出不正确，这将非常有帮助。

• 如果你希望对Octave源代码提出修改建议，请以上下文差异（context diff）的形式发送。如果你讨论了Octave源代码中的某些内容，请根据上下文而非行号来引用，因为开发源码中的行号很可能与你本地源码中的行号不一致。

以下是一些不必要的内容：

• 对错误影响范围的描述。

  通常，遇到错误的人会花大量时间研究对输入文件的哪些更改会使错误消失、哪些更改不会影响它。这些信息通常不是我们在Octave中修复错误所必需的，但如果你能找到更简单的示例来代替原始示例报告，那会方便很多——输出中的错误将更容易发现，在调试器中运行耗时也会更少，等等。大多数Octave错误只涉及一个函数，因此简化示例最直接的方法，就是删除除发生错误的函数之外的所有函数定义。

  不过，简化并非必须；如果你不想这样做，仍然可以报告错误，并把你使用的整个测试用例发过来。

• 错误的补丁。补丁可能有用，但如果你发现了错误，即使无法提供修复方案，也应该报告它。