提交新问题¶

撰写一份好的问题工单或错误报告，对我们排除故障的能力很有帮助。以下是向 BeeWare 提交一份好的错误报告的最佳流程。

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

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

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

在 GitHub 上提交问工单之前，可以先提出讨论话题（discussion）以确定你遇到的问题究竟是 bug 还是你的设置或流程问题。除非你看到的行为与文档中的行为直接矛盾，否则在直接提交错误报告之前，先提出讨论话题可能更好。如果你确实发现了问题，确认后讨论主题可以很容易地被转化为问题。

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

如果确实需要新问题，那么你最好提供尽可能多的细节。一份好的错误报告应包括与错误可能相关的所有信息，以及尽可能小的重现示例。

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

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

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

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

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

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

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

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

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

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

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

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

<details>
<summary>折叠内容标题</summary>
长段落文本。
</details>

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

使用 GitHub CLI 创建问题

直接使用 GitHub CLI (gh) 会绕过我们创建的模板。这些模板的存在是为了确保我们最终能获得处理该问题所需的信息。

如果您打算使用 gh 创建新问题，请按以下方式操作：

gh issue create --web

使用 --web 会打开浏览器并跳转至问题模板页面，让你能够使用相应的模板创建问题。