使用工具¶

我们所能获得的最有价值的反馈信息之一，就是人们在尝试使用BeeWare工具时，发现了其中的摩擦点或功能缺失。了解您在实际使用工具时可能遇到的困难对我们来说非常有用。

想一想你一直想建造的东西，然后试着建造它。如果结果证明你能建造出你的项目，那么恭喜你！你拥有了你一直想要的东西。

但是，如果您没有成功，请告诉我们哪里出了问题。是否有功能缺失？文档是否在某些方面存在混乱或不足？分享您的经验会给我们带来有益的启发，我们可以利用这些启发来制定我们的规划流程。

如果您遇到任何问题，请启动一个新的讨论主题，因为这可能是一个新问题或功能建议的开始。

促进工具的使用¶

提交新问题

撰写一份好的问题或错误报告，对排除故障的能力大有裨益。以下是如何向 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>

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

提出新功能

因此，您对 {{ 正式名称 }} 的改进有了一个想法。- 如何提交该想法以供考虑？

调查研究¶

第一步是搜索 BeeWare 问题跟踪器中现有的功能问题（标记为 "增强 "的问题）。

讨论想法¶

如果您没有找到与您的想法相关的任何现有参考资料，请启动一个[讨论主题]（https://github.com/beeware/beeware/discussions）。对您的想法的目的和用例进行高级描述。包括您对该功能实现后的外观的任何想法，例如 API 的总体形状、功能的视觉外观或将要添加的文档。如果适用，还应包括您就您的想法在不同平台上的表现形式所做的任何研究。

讨论主题开启后，BeeWare 团队和社区的其他成员将作出回应。核心团队的目标是在两个工作日内对您的想法提供至少一个初步印象。如果想法特别复杂，更详细的分析可能需要一周时间。节假日和会议等活动可能会导致上述时间略微延长。

这是您参与有关您想法的对话的机会。我们可能会询问更多细节或背景情况。社区的其他成员也可以参与讨论，提供其他观点、建议或反建议。讨论结果将决定接下来的步骤。

重要的是要明白，并非所有想法都会被接受。这个过程之所以从提案开始，是为了避免你投入了所有的工作，却发现你的改变不被接受是有原因的。

这并不意味着这不是一个好主意！可能有技术原因导致无法实施。例如，在以下情况下，我们可能会拒绝某个想法

很难或不可能在所有支持的平台上可靠地实施；或
难以维护，或维护需要使用尚未普及的技术或软件；或
它为小众用户提供服务，但对其他用户造成了巨大的开销。

如果我们认为您的想法不合适，并不一定意味着您应该放弃。虽然我们可能会拒绝某个具体的想法，但我们可能会更乐于为您添加一个插件接口或其他扩展点，让您可以将相同的功能作为外部库来维护。这样，您就可以拥有该功能，而不会因为具体的维护问题或功能限制而对项目本身造成制约。

转换为正式功能请求¶

一旦讨论就功能的形式达成共识，您就可以在 BeeWare 问题跟踪器中创建一个新的功能请求问题，对讨论进行总结，并链接到讨论的上下文。

您不必自己实现您的功能建议；您可以打开一个问题，详细说明您的建议。但是，仅仅发布问题并不意味着它就会为您实现。您需要等待对同一功能感兴趣的其他人（无论是其他社区成员还是核心团队）将其采纳；但这并不保证一定会发生。如果您想要保证实现，您需要自己实现，或者花钱请别人代为实现。