实施新功能¶
一旦提案过程结束，您就应该有一个完整的新功能设计。这意味着是时候开始撰写了！
如果您的功能需要在特定平台上实现，那么提案过程应该已经验证了该想法*可以在所有平台上实现。但是，作为首次实现新功能的人员，您并不负责在所有平台上实现新功能。您需要为至少个平台提供完整的实现方案，包括测试。对于其他平台，您需要提供一个 "存根 "实现–该实现提供了裸接口定义，但会引发 "NotImplementedError"（未实现错误）或输出日志消息，说明该行为未在该平台上实现。
实施新功能的一个重要部分是确保该功能有完整的文档。这至少意味着要确保有应用程序接口文档，但也可能需要添加操作指南或主题指南。
贡献新功能¶
搭建开发环境
搭建开发环境¶
设置开发环境的步骤因您参与的项目而异。请从以下选项中选择：
如果您想贡献代码的仓库未列在此列表中，请参考最相关的项目的开发指南。例如，如果您想参与 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
避免范围蔓延
避免范围蔓延¶
当单个贡献所解决的问题或实现的功能大大超出工作开始时的预期时，就会发生 "范围蠕变"。你从一个简单的问题开始；你发现了一个密切相关的问题，并决定将该修复也包括在内；然后是第三个......不知不觉中，你的拉取请求已经关闭了 5 个问题，增加了 3 个新功能，包括数十个文件。
范围蠕变每个人都会遇到。对于经验丰富的开发人员来说，这是一个再熟悉不过的概念；我们都曾多次遇到过，并经历过随之而来的所有问题。
避免范围蠕变有非常实际的原因。贡献越大，工作就越困难。识别边缘情况或潜在问题变得更加困难，这意味着稿件的整体质量可能会下降。当评审者需要处理多个可能互不相关的背景时，评审也会变得更具挑战性。更大的贡献意味着更多的评审意见，作为贡献者，要跟踪多个评审线程可能会变得很困难。甚至您的 GitHub 体验也会受到影响–随着 PR 的大小增加，GitHub 的用户界面也会变慢，这意味着通过 GitHub 界面浏览文件和尝试留下审核意见会变得越来越困难。
任何时候，如果您发现有理由在您的贡献中添加任何不属于原始提案或错误报告明确部分的内容，您就应该考虑您是否正在走向范围蠕变。是否有两个不同的功能可以分开实现？某个功能在实现时是否会有已知的限制或错误，并在后续的拉取请求中修复该错误？错误修复的一部分是否独立于另一部分？如果可以在不改变原始贡献的情况下省略部分变更，那就应该省略。
软件开发始终是一个渐进改进的过程。每个人的贡献都应使代码库在合并后处于更好的状态，但留下错误或部分功能作为未来改进的工作也是完全可以接受的。这可能意味着将一个拉取请求分解成多个部分，以便独立审核，或者记录一个问题，以便其他人可以调查并解决问题。
限制每次投稿的范围对包括你在内的每个人都有帮助。您的审稿人，甚至您自己，都会对此表示赞赏。
实施新功能
编写、运行和测试代码¶
修复一个错误或实现一个功能，都需要你编写一些新代码。
开始编写代码前，请确保已搭建好开发环境，并处于开发分支上工作。
我们有一份代码风格指南，其中概述了为 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.md234.bugfix.md789.removal.1.md789.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 的流程。
您的拉取请求可能需要补充内容（例如[变更说明]），才能进入[审核]阶段。