修复问题

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

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

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

提交问题修复

搭建开发环境

要为 BeeWare 做出贡献，您需要建立一个开发环境。

先决条件

您需要安装以下先决条件。

macOSLinuxWindows

BeeWare 需要 Python 3.10+ 。您还需要一种管理虚拟环境的方法（如 venv）。

您可以运行以下命令来验证所安装的 Python 版本：

Python 3.8.10（默认，2020年7月20日 16:16:00）

如果安装了多个版本的 Python，可能需要用特定的版本号（例如，python3.13）替换python3。

我们建议避免使用最近发布的 Python 版本（即带有".0 "或".1 "微版本号的版本，如 3.14.0）。这是因为在 macOS 上支持 Python 所需的工具经常滞后，而最近发布的稳定 Python 版本通常又不可用。

BeeWare 需要 Python 3.10+ 。您还需要一种管理虚拟环境的方法（如 venv）。

您可以运行以下命令来验证所安装的 Python 版本：

Python 3.8.10（默认，2020年7月20日 16:16:00）

如果安装了多个版本的 Python，可能需要用特定的版本号（例如，python3.13）替换python3。

我们建议避免使用最近发布的 Python 版本（即带有".0 "或".1 "微版本号的版本，如 3.14.0）。这是因为在 Linux 上支持 Python 所需的工具通常会滞后，而最近发布的 Python 稳定版本通常又不可用。

BeeWare 需要 Python 3.10+ 。您还需要一种管理虚拟环境的方法（如 venv）。

您可以运行以下命令来验证所安装的 Python 版本：

C:\...>py -3 --version

如果安装了不止一个版本的 Python，可能需要用特定的版本号替换 -3（例如，-python3.13）。

我们建议避免使用最近发布的 Python 版本（即带有".0 "或".1 "微版本号的版本，如 3.14.0）。这是因为在 Windows 上支持 Python 所需的工具通常会滞后，而最近发布的稳定 Python 版本通常又不可用。

设置开发环境

为 BeeWare 设置开发环境的推荐方法是使用 虚拟环境，然后安装 BeeWare 的开发版本及其依赖项。

克隆 BeeWare 仓库

接下来，访问 GitHub 上的 BeeWare 页面，如果还没有的话，将 fork 仓库 添加到自己的账户中。然后，点击 fork 上的"<>代码 "按钮。如果你的电脑上安装了 GitHub 桌面程序，可以选择 "用 GitHub 桌面打开"；否则，复制所提供的 HTTPS URL，然后用命令行将仓库克隆到你的电脑上：

macOSLinuxWindows

分叉 BeeWare 版本库，然后：

$ git clone https://github.com/<您的用户名>/beeware.git

(用您的 GitHub 用户名代替）

分叉 BeeWare 版本库，然后：

$ git clone https://github.com/<您的用户名>/beeware.git

(用您的 GitHub 用户名代替）

分叉 BeeWare 版本库，然后：

C:\...>git clone https://github.com/<您的用户名>/beeware.git

(用您的 GitHub 用户名代替）

设置上游存储库

克隆分支后，将 BeeWare 仓库添加为 upstream 远程仓库。这使本地克隆获得对原始仓库的引用，便于后续同步更新。

你还需要从 upstream 中获取标签，以便 Toga 和 Briefcase 等工具能够解析准确的版本号：

macOSLinuxWindows

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

若需在分叉中包含这些标签，可将其推送：

$ git push --tags

这在您后续创建新克隆时可能很有用，可让分支中的标签在您的分叉中可用。

创建虚拟环境

要建立虚拟环境并升级 pip，请运行

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

现在，您的提示符前面应该有(.venv)前缀。

安装 {{ 正式名称 }}

有了源代码，就可以在开发环境中 编辑安装 BeeWare 了。运行以下命令

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

启用预提交

BeeWare 使用一个名为 pre-commit 的工具来识别简单的问题并规范代码格式。它通过安装一个 git 钩子，在完成任何 git 提交之前自动运行一系列代码精简器。要启用预提交，请运行

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

现在，您可以开始对 {{ 正式名称 }} 进行黑客攻击了！

从分支工作

在你开始修改之前，请确保你已经创建了一个分支。默认情况下，当你克隆你的版本库分叉时，你将在 "主 "分支上签出。这是 BeeWare 的 main 分支的直接副本。

虽然您可以从您的 "主 "分支提交拉取请求，但最好不要这样做。如果您提交的拉取请求几乎*正确，那么审查您的拉取请求的核心团队成员可能会做出必要的修改，而不是给出反馈，要求您做细微的改动。但是，如果你从你的 "主 "分支提交拉取请求，审查人员就无法进行修改。

在完成第一个拉取请求后，在主分支上工作也会给你带来困难。如果你想处理第二个拉取请求，你需要有一个上游项目主分支的 "干净 "拷贝作为你第二次贡献的基础；如果你已经从你的 "主 "分支做了第一次贡献，你就不再有那个干净的版本可用了。

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

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

macOSLinuxWindows

(.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 所执行的操作。

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

macOSLinuxWindows

(.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 应该能够找到并使用它。

仅运行测试套件

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

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

运行部分测试

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

macOSLinuxWindows

(.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 上运行测试套件，请执行以下命令：

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

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

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

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

macOSLinuxWindows

(.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 上运行测试套件并生成覆盖率报告，请执行以下命令：

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

主机平台覆盖报告

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

macOSLinuxWindows

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

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

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

HTML 中的覆盖率报告

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

macOSLinuxWindows

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

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

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

这不仅仅是写测试！

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

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

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

构建文档

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

您必须***在您的路径上安装了 Python 3.13 解释器并可用（即 python3.13 必须启动 Python 3.13 解释器）。

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

实时文档预览

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

实时预览将带警告构建！

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

警告 "不同于 "错误"。如果引入了一个被认为是 "错误 "的问题，实时服务就会失败，需要重新启动。在警告问题解决之前，它不会再次启动。

启动实时服务器：

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

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

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

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

INFO    -  [11:18:51] 正在访问 http://127.0.0.1:8000/

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

docs-live 只是第一步

运行 "docs-live "来使用实时服务器是为了进行初始迭代。在提交拉取请求之前，您应该**运行本地构建。

本地构建

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

生成本地构建

若想要生成本地构建：

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

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

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

生成本地翻译版本

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

生成所有可用翻译的构建文件：

macOSLinuxWindows

(动词) $ tox -e docs-all

(动词) $ tox -e docs-all

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

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

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

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

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

单语言编译的输出将位于 _build 目录中。

文件整理

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

macOSLinuxWindows

(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来帮助为每个版本创建发布说明。当您向相关工具提交拉取请求时，需要包含变更说明–该变更说明将成为发行说明中描述变更的条目。

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

有五种片段类型：

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

变更说明中的描述应从用户角度出发，对变更进行高层次的 "营销 "总结，而不是深层次的技术描述或实现细节。它有别于提交信息–提交信息描述的是所做的工作，以便未来的开发人员了解变更的原因；而变更说明则是为了用户的利益而描述，因为用户可能并不了解内部知识。

例如，如果您修复了一个与项目命名有关的 Bug，提交信息可能会写成这样："......"：

应用更强的正则表达式检查，禁止使用以数字开头的项目名称。

相应的变更说明内容如下

项目名称不能再以数字开头。

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

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

有关 towncrier 和片段类型的更多信息，请参阅 新闻片段。你还可以在 BeeWare 版本库的 changes 目录中查看现有的新闻片段示例。如果该文件夹是空的，很可能是因为 BeeWare 最近发布了新版本；每次发布都会删除变更注释文件，然后合并更新 release notes。您可以查看该文件，了解所需的注释样式；也可以查看 最近合并的 PRs ，了解变更注释的格式。

提交拉取请求

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

使用预提交

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

macOSLinuxWindows

(.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 "会自动修复问题；因此你可以重新添加任何因提交前检查而被修改的文件，并重新提交更改。不过，有些检查需要你手动修改。完成这些修改后，重新添加任何修改过的文件，并重新提交。

macOSLinuxWindows

(.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。

macOSLinuxWindows

(.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 命令，并填写提示。
• 使用 GitHub CLI gh pr create --web 命令打开网页浏览器，进入 PR 创建页面。

这些选项中的任何一个都能让您创建新的拉取请求。

GitHub 命令行界面：gh

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

拉取请求内容

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

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

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

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

持续集成

持续集成，或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 的流程。