提交新问题¶

撰写一份好的问题或错误报告，对排除故障的能力大有裨益。以下是如何向 BeeWare 提交一份好的错误报告。

在提交新问题之前，请在索引中搜索与您的问题相匹配的现有问题。如果有与您的问题相匹配的现有开放问题，请在该问题上添加评论，并提供有关您的经验的任何附加信息。例如，如果您在不同的 Python 版本或不同的操作系统上看到了问题，那么这些附加信息将有助于确定问题的影响或原因。

如果您发现一个已关闭的问题似乎与您的问题相符，请查看该问题最近关闭的时间。如果问题是最近关闭的，这很可能意味着您的错误已被修复，并将在下一个版本中修正。如果问题是在 4 个月前关闭的，那么您遇到的很可能是另一个问题，无论错误信息看起来多么相似。

如果您没有找到与您所看到的内容相匹配的问题，那么可能需要打开一个新问题。

在 GitHub 上提交问题之前，可以先讨论一下您遇到的问题究竟是 bug 还是您的设置或流程问题。除非您看到的行为与文档中的行为直接矛盾，否则在直接提交错误报告之前，还是应该先提出问题。如果您**发现了一个问题，讨论主题可以很容易地转化为问题。

发起讨论还有助于确保您在最佳位置报告问题。虽然您可能在使用 BeeWare 时遇到了问题，但该问题可能是由 BeeWare 生态系统中其他项目的错误引起的。

如果**需要一个新问题，就必须提供尽可能多的细节。一份好的错误报告包括与错误可能相关的所有信息，以及尽可能小的重现示例。

重现示例应尽可能短小精悍，同时仍能展示错误。提供一个庞大的示例会大大增加排除故障的难度，尤其是当示例依赖于其他库，或需要大量有关预期行为或示例内部逻辑的知识时。

我们需要您提供尽可能多的细节。这包括但绝对不限于：

你的操作系统版本–精确到微缩版本（例如，macOS 15.7.2）。
您的 Python 版本，也精确到微型版本（例如 3.14.1）。
您是如何安装 Python 的？是从 python.org 下载的？使用 Homebrew？uv?pyenv？conda？其他的？
您使用的 BeeWare 工具的具体版本（例如 Toga 0.5.3）。如果您使用的是开发版本，那么您使用的 Git 哈希值是多少？只说 "当前主分支 "是不够的，因为主分支每天都在变化。
要触发问题必须安装的其他软件包的具体版本。您可以包含运行 python -m pip freeze 的结果来提供这些信息。
如果已生成日志文件，则整个日志文件。
如果已生成堆栈跟踪，请提供整个堆栈跟踪。不要只提供最终的错误信息，完整的堆栈跟踪上下文非常重要。最好以文本格式提供，而不是*截图。
您的计算机或网络设置是否有其他可能影响问题解决的因素。您的电脑是否较旧或较慢？您的工作电脑是否安装了防火墙、病毒检查程序或其他限制？您的网络是否特别慢？您是否在运行操作系统时使用了异常的系统默认设置（如启用了超大字体或其他辅助技术）？

试着跳出条条框框，把你能想到的、可能会影响你所遇到的问题的一切都包括进来。如果你给我们的比我们需要的多，我们就很容易忽略我们不需要的东西。我们不可能想到你遗漏的东西。

错误报告中最重要的部分是最基本的重现案例。第三方应该能够阅读您的重现案例的说明，并按照这些说明操作，观察到相同的问题。这可能意味着要提供一个显示该问题的示例项目，或者更好的是使用一个已有的示例（例如作为现有代码库一部分的教程或示例项目）。

您的完整项目***不是最小重现案例。最小重现案例不应包含制造问题所绝对不需要的代码。在编写重现案例时要毫不留情–如果制造问题不需要某个按钮，就不要包含该按钮。

通常情况下，开发这种最小重现案例的过程会揭示问题的根源，因为创建最小示例的行为会迫使你找出导致问题的确切原因，无论是代码中的错误，还是源于不正确的假设或 API 使用。

在任何复制说明中，你也应该**明确。说 "关闭示例应用程序 "可能意味着点击窗口上的关闭按钮、从菜单中选择 "退出 "或在终端中键入 Control-C。您的报告应明确说明重现问题所需的步骤。

导航至项目问题列表，点击"新建问题"按钮，选择"错误报告"以开始操作流程。

您必须填写问题模板中的 ** 所有部分。** 我们提供模板作为提示，帮助您提供必要的信息。请记住，您可以（也应该！）提供比模板要求更多的信息，但我们至少需要模板中的所有信息。

在包含代码时，如果您可以通过现有示例（如 BeeWare 教程）重现代码，则可以提供链接。否则，请在报告中提供代码。代码应采用 Markdown 格式；代码块前后需要三个反标（````）。

如果需要包含较长的文本块，可以使用以下语法使其成为折叠内容：

<details>
<summary>Collapsed content title</summary>
Long block of text.
</details>

提供尽可能多的信息后，点击 "创建 "提交报告。