修复问题¶

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 版本：

$ python3 --version

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

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

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

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

$ python3 --version

如果安装了多个版本的 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/<your username>/beeware.git

(用您的 GitHub 用户名代替）

分叉 BeeWare 版本库，然后：

$ git clone https://github.com/<your username>/beeware.git

(用您的 GitHub 用户名代替）

分叉 BeeWare 版本库，然后：

C:\...>git clone https://github.com/<your username>/beeware.git

(用您的 GitHub 用户名代替）

创建虚拟环境¶

要建立虚拟环境并升级 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 时，您需要验证所报告的问题是否仍然存在。如果是渲染问题，您需要构建文档，看看能否重现问题。内容问题则需要阅读以确认是否有人提交了更新。

更新问题¶

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

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

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

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

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

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

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

编写、运行和测试代码

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development¶

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code¶

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage¶

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

pre-commit hooks
towncrier release note check
documentation linting
test suite for available Python versions
code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations¶

Run tests for multiple versions of Python¶

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite¶

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Run a subset of tests¶

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

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

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version¶

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)¶

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage¶

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results¶

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
总计 7540 0 1040 0 100.0% 0

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

姓名 Stmts Miss Branch BrPart Cover Missing
--------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98.1% 170, 302-307, 320->335
--------------------------------------------------------------------------------
共计 7540 1 1726 0 99.9

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version¶

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Coverage report for host platform¶

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

macOSLinuxWindows

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

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

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

Coverage reporting in HTML¶

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

macOSLinuxWindows

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

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

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

It's not just about writing tests!¶

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

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

/// details-abstract | 构建文档

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



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

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

### 实时文档预览

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

/// warning | 实时预览将带警告构建！

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

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

///

启动实时服务器：



/// tab | macOS



```console
(venv) $ tox -e docs-live

LinuxWindows

(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 "来使用实时服务器是为了进行初始迭代。在提交拉取请求之前，您应该**运行本地构建。

本地构建¶

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

生成本地构建¶

若想要生成本地构建：

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

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

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

生成本地翻译版本¶

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

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

macOSLinuxWindows

(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> 单独运行该单个编译。例如，要只编译法语文档，请运行：

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 中的任何内容。例如

- ./path/to/directory/*

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

- [My new document](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 的流程。