跳转至

修复问题

BeeWare 跟踪 [已知问题] 列表（https://github.com/search?q=org%3Abeeware%20is%3Aopen%20is%3Aissue%20label%3Abug&type=issues）。这些问题中的任何一个都是有待解决的候选问题。

可以通过多种方式过滤该列表。例如，您可以按平台过滤，这样您就可以专注于影响您能够测试的平台的问题；也可以按问题类型过滤，如文档错误。com/search?q=org%3Abeeware+is%3Aopen+is%3Aissue+label%3Abug+label%3Adocumentation&type=issues）。还有一个过滤器用于过滤[好的第一个问题]（https://github.com/search?q=org%3Abeeware+is%3Aopen+is%3Aissue+label%3Abug+label%3A%22good+first+issue%22&type=issues）–这些问题已被确定为具有已知原因的问题，我们认为修复应该相对简单（尽管我们的分析可能有误）。

如果问题已超过 6 个月，那么问题完全有可能已经解决，因此第一步是验证您是否可以重现问题。使用错误报告中提供的信息尝试重现问题。如果您无法重现问题，请将您发现的问题作为该问题的评论进行报告，然后选择另一个问题。

如果您能重现问题，请尝试修复它！找出实现该功能的代码组合，看看能否找出哪些代码不能正常工作。

即使您不能解决问题，也要将您在这一过程中发现的任何问题作为评论报告出来。如果您能找到问题的源头，但无法解决问题，那么对于更了解平台的人来说，这些知识往往足以解决问题。如果该问题还没有提供一个很好的重现案例（一个除了重现问题外什么都不做的小样本应用程序），那么提供一个案例会有很大帮助。

提交问题修复

搭建开发环境

搭建开发环境

设置开发环境的步骤因您参与的项目而异。请从以下选项中选择：

如果您想贡献代码的仓库未列在此列表中，请参考最相关的项目的开发指南。例如，如果您想参与 Briefcase 模板仓库的开发，应参考 Briefcase 的指南。

从分支工作

请在功能分支上工作，而非你的main分支

在你开始修改内容以前，请务必确保你已创建了一个新的分支。当你克隆你的派生 (fork) 版本库时，你将会默认在 main 分支上，即为 BeeWare 的 main 分支的直接副本。

虽然你可以从你的 main 分支提交拉取请求，但这不是最佳方法。如果你提交的拉取请求基本正确，那么审查你的拉取请求的核心团队成员将会直接在你的拉取请求上做出所需的更改，而不会给出反馈以要求你做细微的改动。但是，如果你从你的 main 分支提交拉取请求，审核人员将无法进行直接修改。

在 main 分支上工作也会给你自己完成第一个拉取请求后时带来困难。如果你想贡献第二个拉取请求，你需要有一份上游项目 main 分支的“干净”版本为基础；如果你已经从你的 main 分支做了第一次贡献，你也就不会有另一个干净的版本可用了。

相反，你应该在功能分支上进行修改。功能分支有简单的名称，用来辨别你将会做的更改。例如，如果你要修复一个会导致 Windows 11 上构建问题的错误，您可以创建一个名为 fix-win11-build 的功能分支。如果你修复的问题与已报告的特定工单有关，在分支名称中引用该工单编号也很常见（例如，fix-1234）。

要创建 fix-win11-build 功能分支，运行：

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build
重现该问题

重现问题

如果首先没有问题，就无法解决问题。因此，重现问题是解决问题的前提。在软件中，问题通常被称为"错误"，而问题通常被称为 "错误报告"。

有人提供了一份错误报告。您需要验证报告者所描述的步骤是否导致了所报告的错误。你能否完全按照报告中的描述重现相同的结果？如果不能，就需要找出原因。

要开始重现问题，您需要搭建一个开发环境。

代码中的错误

在理想的情况下，您将拥有与报告错误者相同的设置，您将按照步骤操作，并且您将能够按照描述重现错误。但在很多情况下，这并不那么简单。许多错误报告只包含模糊的解释和一组模糊的条件。问题是，许多错误会根据所涉及的一系列条件而变化，包括与它们交互的方式、各种先决条件、操作系统、操作系统版本、CPU 架构，或者用户的机器是又老又慢还是又新又快。我们掌握的有关错误发生情况的信息越多越好。尝试重现报告者提供的一系列条件。如果无法重现，下一步可能需要向报告错误的人索取更多信息。

重现错误的最佳方法是使用尽可能小的示例，但仍能显示问题。大多数情况下，报告者不会提供最小可行的示例；如果他们提供了**示例，那也是直接从他们的 "现实世界 "应用程序中复制的。您的目标是将报告缩减到最简单的形式，以展示问题。最好的再现案例就是尽可能小的程序。这种还原本身就很有帮助，因为它能确定实际问题是什么。任何人都可以使用最小的示例，运行它，并观察到所描述的错误。

文件中的错误

文档中的错误有多种表现形式。有的是格式问题导致渲染问题。有时，这甚至不是一个错误；有关人员可能误读了文档，或者犯了一个真正的错误。这并不一定意味着文档没有问题。文档内容可能不清晰或不准确，给混淆或误解留下了空间。也有可能一个应该讨论的概念没有讨论，因为它完全没有文档记录。

当针对文档问题提交 bug 时，您需要验证所报告的问题是否仍然存在。如果是渲染问题，您需要构建文档，看看能否重现问题。内容问题则需要阅读以确认是否有人提交了更新。

更新问题

分流流程的最后一步是通过在问题上留下评论来记录您的发现。

如果您能完全按照描述重现问题，那就足够了。请留下评论，说明您已确认您看到了相同的问题，与原始报告者描述的方式完全一致。

如果您能够提供任何其他背景信息，那么请提供背景信息的详细信息。这可能包括能够在不同的操作系统上重现问题，或使用不同版本的相关软件，或任何其他与原始报告不同的内容。

如果原始报告中缺少您重现报告所需的细节，请将这些细节包括在内。这可能包括提供原始报告没有提供的操作系统或版本详细信息、更完整的日志或堆栈跟踪，或者更清晰地说明重现问题所需的确切操作顺序。如果您已经开发出一种更简单的方法来重现问题（或者原始报告者没有提供重现案例），您可以包含该重现方法的详细信息。

若您无法复现该问题，也请留言说明尝试过的操作。了解问题不存在的位置与存在的位置同样重要，这有助于缩小可能的成因范围。 若您对无法复现问题的原因有任何推测——例如认为是使用错误所致，或近期操作系统更新已解决该问题——请将这些推测纳入评论说明。

最后，您可以向核心团队提出任何建议。如果您认为原始报告有误，建议关闭该问题；如果您对问题的原因有自己的看法，也可以提出建议。您的意见将有助于核心团队确定如何将问题推进到下一步。

此时，你可以尝试修复刚刚复现的问题；或者，你可以记录下你的发现，并尝试复现另一个问题。

如果修复问题需要修改代码：

编写、运行和测试代码

编写、运行和测试代码

修复一个错误或实现一个功能，都需要你编写一些新代码。

开始编写代码前，请确保已搭建好开发环境，并处于开发分支上工作。

我们有一份代码风格指南，其中概述了为 BeeWare 编写代码的规范。

测试驱动开发

确保代码能按预期运行的一个好方法是，先编写一个测试用例来验证它。这个测试用例起初应该会失败，因为它所测试的代码尚未存在。然后，你可以编写必要的代码修改以使测试通过，从而确信你所编写的代码确实解决了预期中的问题。

运行您的代码

编写完代码后，你需要确保它能够运行。你需要手动运行代码，以验证其运行结果是否符合预期。如果你尚未这样做，建议为所做的修改编写一个测试用例；如上所述，如果代码被注释掉或不存在，该测试应失败。

您将把测试用例添加到测试套件中，以便与其他测试一起运行。下一步是运行该测试套件。

运行测试 及覆盖率

BeeWare 使用 tox 来管理测试流程，并使用 pytest 作为其自身的测试套件。

默认的 tox 命令包括执行：

  • 提交前钩子
  • towncrier 版本说明检查

  • 文档代码检查

  • 适用于现有 Python 版本的测试套件

  • 代码覆盖率报告

这基本上就是你在提交拉取请求时，CI 所执行的操作。

要运行完整的测试套件，请执行：

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

运行完整的测试套件可能需要一段时间。您可以通过并行运行 tox 来显著加快速度，具体方法是运行 tox p（或 tox run-parallel）。当您并行运行测试套件时，虽然在运行过程中收到的进度反馈会减少，但在测试结束时仍会获得发现问题的汇总报告。您应该会看到一些表明测试已运行的输出信息。 您可能会看到 SKIPPED 条测试，但绝不应该看到任何 FAIL 或 ERROR 的测试结果。我们在合并每个补丁之前都会运行完整的测试套件。如果该过程发现任何问题，我们就不会合并该补丁。如果您确实发现了测试错误或失败，要么是您的测试环境存在异常，要么是您发现了一个我们之前未曾遇到的边界情况——无论哪种情况，请务必告知我们！

除了测试通过外，这还应显示 100% 测试覆盖率。

运行测试变体

针对多个 Python 版本运行测试

默认情况下，许多 tox 命令会尝试多次运行测试套件，每次对应 BeeWare 支持的一个 Python 版本。不过，要实现这一点，您的机器上必须已安装每个 Python 版本，并且 tox 的 Python 检测 过程能够识别到它们。通常来说，如果某个 Python 版本可以通过 PATH 识别，那么 tox 应该能够找到并使用它。

仅运行测试套件

如果你正在对新功能进行快速迭代，则无需运行完整的测试套件；你可以仅运行单元测试。要实现这一点，请运行：

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

运行部分测试

默认情况下，tox 会运行单元测试套件中的所有测试。在开发新测试时，可能需要“仅”运行该测试。为此，您可以将 任何 pytest 指定符 作为参数传递给 tox。这些测试路径相对于 briefcase 目录。例如，若要仅运行单个文件中的测试，请执行：

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

即使只运行测试套件的一部分，您仍然会收到覆盖率报告——但覆盖率结果只会报告您所运行的特定测试所执行的代码行。

运行特定 Python 版本的测试套件

默认情况下，tox -e py 将使用您机器上解析为 python 的任意解释器运行。如果您安装了多个 Python 版本，并且希望从已安装的版本中测试某个特定版本，可以指定要使用的具体 Python 版本。例如，要在 Python 3.10 上运行测试套件，请执行以下命令：

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

通过在命令行中添加 -- 和测试规范，可以运行 测试子集。

不带覆盖率的测试套件（快速）

默认情况下，tox 会以单线程模式运行 pytest 测试套件。您可以通过并行运行测试套件来加快其执行速度。由于在子进程中捕获覆盖率较为复杂，此模式不会生成覆盖率文件。若要在“快速”模式下运行单个 Python 版本，请执行以下命令：

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

可以通过在命令行中添加 -- 和测试规范来运行 测试子集；可以通过在测试目标中添加版本号来使用 特定的 Python 版本（例如，py310-fast 可在 Python 3.10 上快速运行）。

代码覆盖率

BeeWare 的代码库保持 100% 的分支覆盖率。当您在项目中添加或修改代码时，必须添加测试代码，以确保对所做的任何更改进行覆盖。

然而，BeeWare 支持多个平台以及多个 Python 版本，因此无法在单一平台和 Python 版本上验证完整的代码覆盖率。 为解决这一问题，在 tool.coverage.coverage_conditional_plugin.rules 的 pyproject.toml 部分定义了若干条件覆盖规则（例如，no-cover-if-is-windows 可用于标记在 Windows 上运行测试套件时不会被执行的代码块）。这些规则用于识别仅在特定平台或 Python 版本上被覆盖的代码段。

需要注意的是，不同 Python 版本之间的覆盖率报告可能会有些特殊情况。例如，如果覆盖率文件是在某个 Python 版本下生成的，但报告是在另一个版本下生成的，那么报告中可能会出现因分支遗漏而导致的误报。因此，生成覆盖率报告时，应始终使用生成覆盖率文件时所用的最旧的 Python 版本。

理解覆盖结果

在覆盖率测试输出的末尾，应包含一份关于所收集覆盖率数据的报告：

名称    报表   缺失分支   分支部分   覆盖率   缺失
 ---------------------------------------------------
 合计    7540 0   1040 0  100.0%

这表明测试套件已经执行了代码中所有可能的分支路径。虽然这不能100%保证没有缺陷，但确实意味着我们已经对代码库中的每一行代码都进行了测试。

如果您对代码库进行了修改，可能会导致代码覆盖率出现缺口。一旦发生这种情况，覆盖率报告会告诉您哪些代码行未被执行。例如，假设我们对 some/interesting_file.py 进行了修改，添加了一些新逻辑。覆盖率报告可能如下所示：

名称 语句   缺失 分支 BrPart  覆盖率   缺失
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98.1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 总计 7540 1     1726 0  99.9%

这表明第 170 行、第 302-307 行以及从第 320 行跳转到第 335 行的分支，均未被测试套件执行。您需要添加新的测试（或修改现有测试）来恢复该代码覆盖率。

主机平台和 Python 版本的覆盖率报告

您可以针对您所使用的 Python 平台和版本生成覆盖率报告。例如，若要在 Python 3.10 上运行测试套件并生成覆盖率报告，请执行以下命令：

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

主机平台覆盖报告

如果 tox 可用所有受支持的 Python 版本，则可通过运行以下命令报告主机平台的代码覆盖率：

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

HTML 中的覆盖率报告

通过在任何覆盖率 -html 环境名称后添加 tox，即可生成 HTML 覆盖率报告，例如：

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

这不仅仅是写测试！

尽管我们确保对所有代码都进行了测试，但这项工作不仅仅是维持这种测试水平。其中一部分工作是在开发过程中对代码进行审查。你可以为一件混凝土救生衣编写一套全面的测试用例……但这件混凝土救生衣对于其原本的用途来说，依然毫无用处！

在编写测试时，你还应检查核心模块在内部是否也具有一致性。 如果您发现任何方法名称在内部不一致（例如，某个方法在某个模块中名为 on_select，但在另一个模块中却名为 on_selected），或者数据处理方式不一致，请标记该问题并通过提交工单告知我们。或者，如果您确信自己知道该如何处理，请创建一个拉取请求来修复您发现的问题。

当您完成所有操作后，即可提交包含您修改内容的拉取请求。

如果解决问题需要修改文件：

构建文档

建筑文件

在对 BeeWare 的文档进行任何更改之前，最好先确认您可以构建现有文档。

在构建文档之前，请确保已设置好开发环境。

你必须在你的 PATH 上安装 Python 3.13 解释器，并确保它可用（即确保 python3.13 可以启动 Python 3.13 解释器）。

BeeWare 使用 tox 构建文档。以下 tox 命令必须在与 tox.ini 文件相同的位置运行，也就是在项目的根目录下。

实时文档预览

为支持文档的快速编辑，BeeWare 文档具有“实时预览”模式。

实时预览构建不受警告影响！

实时预览服务器可用于迭代文档更改。在更改过程中，你可能会引入标记问题。被视为 WARNING 的问题会导致标准构建失败，但实时预览服务器只会在控制台输出中显示警告，并同时继续构建。这样，你可以继续进行迭代，而无需重新启动实时预览。

WARNING 不同于 ERROR。如果你引入了一个 ERROR 类问题，实时预览服务器就会失败，需要重新启动。在 WARNING 问题解决之前，它无法被重新启动。

启动实时服务器：

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

这将构建文档，启动网络服务器以提供它，并监视文件系统是否对文档源代码进行了任何更改。

服务器启动后，你会在控制台输出中看到类似下面的内容：

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

打开浏览器，并导航到显示的 URL。现在你就可以开始迭代文档了。如果检测到更改，文档将被重新构建，任何查看修改后页面的浏览器都将被自动刷新。

docs-live 只是第一步

使用 docs-live 使用实时预览服务器是为了进行初始迭代。在提交拉取请求之前，你务必运行本地构建。

本地构建

完成迭代后，你需要对文档进行本地构建。如果出现任何标记问题，这个构建过程就会失败。这样，您就可以发现在实时预览构建上可能遗漏的任何问题。

生成本地构建

若想要生成本地构建：

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

构建的输出结果将保存在项目根目录下的 _build 目录中。

构建本地翻译版本

BeeWare 的文档被翻译成多种语言。对英文文档的更改有可能导致其他语言版本出现构建问题。因此，在提交拉取请求之前，请务必确认所有语言版本都能正常构建。

构建所有可用翻译：

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

每种语言文档构建的输出结果将保存在语言相关的 _build/html/<languagecode> 目录中，其中 <languagecode> 是与特定语言相关的两个或五个字符的语言代码（例如 fr 表示法语，it 表示意大利语等）。

如果您发现单个编译存在问题，可以运行 tox -e docs-<languagecode> 单独运行该单个编译。例如，要只编译法语文档，请运行：

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

单语言构建的输出将位于 _build 目录中。

运行文档 lint

构建过程会识别 Markdown 问题，但 BeeWare 还会执行一些额外的样式和格式检查，即所谓的 "linting"。要运行 "linting "检查:

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

这将确保文件没有：

  • 死超链接
  • 错别字

如果一个单词的有效拼写被识别为拼写错误，则将该单词添加到 docs/spelling_wordlist 中的列表中。这将把该词添加到拼写检查程序的词典中。添加到该列表时，请记住：

  • 我们倾向于使用美式拼写法，但对程序特定的口语（如 "apps"）和名词的动词化（如 "scrollable"）有一定的自由度
  • 任何对产品名称的引用都应使用该产品的首选大写方式。(例如，"macOS"、"GTK"、"pytest"、"Pygame"、"PyScript"）。
  • 如果一个术语被“作为代码”使用，那么它就应该作为字面格式（像这样）被引用，而不是被添加到拼写词典中。

成功构建文档后，您就可以开始编写文档了。

编写文档

编写文档

以下是为 BeeWare 撰写文档的步骤。

在开始编写文档之前，请确保您能够构建文档，并且您正在分支上工作。

更新现有文件

如果您要编辑现有文档，则需要在 /docs/en 目录中找到该文件。文件结构与页面结构一致，因此可以使用文档 URL 查找文件。

添加新文件

如果要添加新文件，还需要几个步骤。

您需要在 docs/en 目录中的适当位置创建文档。为了便于讨论，我们假设你要添加一个文件名为 new_doc.md 的新文档。

然后，你需要更新 docs/en/SUMMARY.md 文件以包含你的新文件。SUMMARY.md 的组织结构基本上反映了 docs/en 目录的结构，但更重要的是，它直接决定了左侧边栏的结构。如果您找到了打算包含 new_doc.md 的部分，如果看到列出的通配符路径，则无需更改 SUMMARY.md 中的任何内容。例如

- ./路径/到/目录/*

如果您打算包含 new_doc.md 的部分是一个单独的 Markdown 链接列表，您需要为您的链接添加一个明确的链接。例如

- [我的新文档](new_doc.md)

编写文件

现在，您可以在编辑器中打开所需的文件，开始写作。

我们有一份文档风格指南，概述了我们为 BeeWare 编写文档的指导方针。

当您对新文档感到满意后，即可提交包含拟定修改内容的拉取请求。

当您准备提交稿件时：

添加变更说明

为发布说明添加变更信息

许多 BeeWare 工具都使用 towncrier 来帮助编写版本发布说明。当您向相关工具提交拉取请求时，需要包含变更说明——该变更说明将成为发行说明中描述变更的条目。

每个拉取请求（PR）都必须在 changes/ 目录中包含至少一个文件，对拉取请求中的变更进行简短描述。变更说明应采用 Markdown 格式，文件名应为 <id>.<片段类型>.md。如果你提出的变更将修复一个已有工单编号的问题或实现一个已有工单编号的功能，ID 就是该工单编号。如果变更没有对应的工单，则可以使用 PR 编号作为 ID。在推送拉取请求之前，您不会知道 PR 编号，因此第一次 CI 通过时，towncrier 检查会失败；添加变更注释并推送 PR 更新后，CI 才应该会通过。

有五种变更片段类型：

  • feature：拉取请求（PR）增加了以前不可能的新行为或功能（例如，增加了对新包装格式的支持，或在现有包装格式中增加了新功能）；
  • bugfix：该 PR 修复了现有实现中的一个错误；
  • doc：PR 是对文档的重大改进；
  • removal； PR 代表 BeeWare API 向后不兼容的更改；或
  • misc; 不需要在发布说明中公布的细微或管理性变更（如修正错字、细微的语言澄清或更新依赖版本）。

变更说明中的描述应从用户角度出发，使用“营销”的方式总结变更，且不包含深层次的技术描述或实现细节。它有别于提交信息（commit message）——提交信息丛“以便未来的开发人员了解变更的原因”的角度描述了所做的工作；而变更说则直接描述了对用户的好处，因为用户可能并不了解内部知识。

例如，如果你修复了一个与项目命名有关的问题，那么提交信息可能会写成这样：

Apply stronger regular expression check to disallow project names that begin with digits.\ \ （应用更强的正则表达式以禁用任何以数字开始的项目名称。）

相应的变更说明内容如下：

Project names can no longer begin with a number.\ \ （项目名称不能再以数字开头。）

有些 PR 会引入多个功能并修复多个错误，或者引入多个向后不兼容的变更。在这种情况下，PR 可以包括多个变更说明片段。如果需要将两个片段类型与同一个工单编号关联，可以在文件名中添加一个数字后缀。例如，如果 PR #789 添加了工单 #123 所描述的功能，修复了工单 #234 所描述的错误，还做了两项向后不兼容的更改，那么 PR 中就会有 4 个变更说明文件：

  • 123.feature.md
  • 234.bugfix.md
  • 789.removal.1.md
  • 789.removal.2.md

有关 towncrier 和片段类型的更多信息，请参阅新闻片段节。你还可以在 BeeWare 仓库的 changes 目录中查看现有的变更片段示例。如果该文件夹是空的，很可能是因为 BeeWare 刚刚发布了新版本；每次发布版本时，towncrier 都会删除变更说明文件，并将它们的内容合并为版本发布说明。您可以查看该文件，了解变更说明所需的编写格式；也可以查看最近合并的拉取请求 ，了解变更说明的格式。

提交拉取请求

提交拉取请求

现在您已经提交了所有更改，可以提交拉取请求了。为确保审核过程顺利，您需要采取一些步骤。

使用预提交

提交任何更改时，预提交会自动运行。如果在提交过程中发现任何问题，都会导致提交失败。在可能的情况下，pre-commit 会对发现的问题进行必要的修改。在下面的示例中，"ruff "检查发现了一个代码格式问题：

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

在这种情况下，"ruff "会自动修复问题；因此你可以重新添加任何因提交前检查而被修改的文件，并重新提交更改。不过，有些检查需要你手动修改。完成这些修改后，重新添加任何修改过的文件，并重新提交。

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

一切通过后，您会看到一条提交已最终完成的消息，而您的 git 日志也会显示您的提交是最新的。现在就可以推送到 GitHub 了。

将更改推送到 GitHub 并创建拉取请求

第一次向 GitHub 推送时，系统会提供一个 URL，让你直接进入 GitHub 页面创建新的拉取请求。按照 URL 创建您的拉取请求。

下面的示例显示了push时的预期结果，并突出显示了 URL。

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

如果您已将当前分支推送到 GitHub，就不会再收到该 URL。不过，还有其他方法可以获取 PR 创建 URL：

  • 导航至上游版本库，点击 "拉取请求"，然后点击 "新建拉取请求"，选择要提交拉取请求的版本。
  • 如果您最近推送过，请导航到上游版本库，找到文件列表上方显示该版本库 "最近推送过 "的横幅，然后点击 "比较和拉取请求 "按钮。
  • 使用 GitHub CLI gh pr create --web 命令打开网页浏览器，进入 PR 创建页面。

GitHub 命令行界面：gh

GitHub 提供GitHub CLI，让你可以在终端通过 gh 命令访问 GitHub 的许多功能。GitHub CLI 文档](https://cli.github.com/manual/)涵盖了所有功能。

gh pr create

请不要使用裸露的 gh pr create 命令来创建拉取请求。BeeWare 项目采用拉取请求模板，我们要求所有贡献都必须遵循该模板。gh pr create 命令会绕过该模板的使用。

拉取请求内容

拉取请求的标题必须翔实、清晰、简洁。尽可能保持简短，但如果需要，也可以使用较长的标题。一个好的拉取请求标题应该能让人在没有任何上下文的情况下，对您的拉取请求所实现的错误或功能有一个合理的概念。

您的拉取请求必须遵循 BeeWare 拉取请求模板。如果您是通过 GitHub 网页界面创建拉取请求的，该模板将作为拉取请求说明的起始内容。如果您无意中未使用此模板创建了拉取请求，可以编辑该拉取请求以添加模板内容——但模板内容必须提供并正确填写。

PR 说明必须清楚地反映 PR 中的变更。一个没有任何背景的人应该能够读懂你的描述，并相对完整地理解为什么要进行修改。避免使用笑话、成语、口语和不必要的格式，如使用大写字母或过多的标点符号；这样做的目的是直截了当地解释您的公关中发生了什么，避免使用这些内容会使他人更容易理解您的描述。

如果有任何重现案例或您使用的任何测试方案尚未成为 PR 中更改的一部分，则应在 PR 中加以解释和包含。解释应包括如何运行它们，以及如何才能重现所需的结果。

如果您的拉取请求将解决 #1234 问题，则应在拉取请求描述中包含文本 Fixes #1234。这将导致该问题在拉取请求合并时自动关闭。你可以使用相同的 #1234 语法引用其他讨论、问题或拉动请求。你也可以通过在编号前加上前缀来引用不同版本库中的问题，例如 python/cpython#1234 就引用了 CPython 版本库中的问题 1234。

AI 工具特别容易生成冗长且无用的拉取请求说明。如果您使用 AI 工具生成拉取请求，您有责任确保拉取请求说明简洁明了，且仅包含对审查过程有帮助的信息。 例如，你无需包含描述如何运行测试套件的“测试方案”细节，也不必提供“修复理由”来解释为何需要修复该 bug。过于冗长的拉取请求正文可能会导致你的拉取请求在未经审查的情况下被关闭，因为这无视了核心团队有限的资源。

BeeWare 拉取请求模板

BeeWare 拉取请求模板 绝非可选项。 我们要求所有拉取请求都必须遵循此模板。如果您的拉取请求缺少“PR 检查清单”部分，或者您对复选框问题的回答不完整或不一致，您的拉取请求将不会被审核。如果您使用了 AI 工具来生成拉取请求，您必须勾选相应的复选框，并在“Assisted-by:”行中提供详细信息。

持续集成

持续集成，或CI，是对您的拉取请求进行自动检查的过程。这可能包括简单的检查，如确保代码格式正确；但也包括运行测试套件和构建文档。

有很多变更都可能导致 CI 失败。一般来说，我们不会审核未通过 CI 的 PR。如果您创建了一个拉取请求，但 CI 失败了，我们也不会开始审核，直到它通过为止。如果您的更改导致失败，您有责任查明原因并解决问题。

当 CI 失败时，失败链接将显示在 PR 页面底部的 "某些检查不成功 "标题下。您会看到一个失败检查列表，如果还有通过的检查，该列表会显示在所有检查列表的顶部。如果点击失败链接，就会跳转到日志。日志通常会提供您所需的所有信息，帮助您找出故障原因。阅读日志并尝试找出故障发生的原因，然后采取必要的措施加以解决。

有时，CI 检查会因为与您的更改无关的原因而失败。这可能是由于运行 CI 检查的机器出现了问题，也可能是因为 CI 检查不稳定。如果您看到了失败，而且非常确定与您的更改无关，请在您的 PR 中添加相关注释，我们会进行调查。

要触发新的 CI 运行，需要向分支推送新的变更。

如果您遇到需要帮助才能通过 CI 的情况，请在 PR 上留言告诉我们，我们会尽力提供帮助。

提交前 "和 "提交者 "检查

如果 "pre-commit "或 "towncrier "检查失败，将阻止大部分其他 CI 检查的运行。您需要先解决相关问题，然后才能运行全套检查。

我们的 CI 资源有限。要知道，每次向分支推送时，CI 都会启动。如果要进行大量修改，最好在本地进行修改，然后一次性推送。CI 只会批量运行最新的提交，从而将 CI 系统的负载降至最低。

只有在通过 CI 审查，或者您能解释为何未通过 CI 审查时，才算完成了提交 PR 的流程。

您的拉取请求可能需要补充内容（例如[变更说明]），才能进入[审核]阶段。