添加文档

您可能拥有世界上最好的软件，但如果没有人知道如何使用，那又有什么意义呢？文档总是可以改进的，我们需要您的帮助！

文档表单

BeeWare 的文档使用 MkDocs 和 Markdown 编写。我们的目标是遵循 Diataxis 框架来构建文档。

Diataxis 框架描述了四种 "形式 "的文件：

• 教程 - 有指导的学习体验，有特定的项目终点。
• 操作指南 - 引导读者实现特定目标或结果的说明。
• ** 主题指南** - 对单一观点的讨论，其解释方式应使基本概念清晰明了。
• ** 参考资料** - 特定应用程序接口或其他接口的技术说明。

在开始任何文档贡献之前，重要的是确定哪种形式最合适。许多文档提案最初都会被描述为要求提供 "关于 X 的教程"–但在大多数情况下，实际需要的是如何操作、主题指南或改进的参考信息。

举例来说，编写有关烤饼干的文档是一项艰巨的任务。

教程

教程是一种介绍，尤其是针对初学者的介绍，其目标应该是让读者从一个简洁的起点到完成一个产品。它需要非常具体的说明和详细的解释，将教程步骤与上下文联系起来。您必须不假思索地假设读者对所讲解工具的使用经验，尽管假设他们对 Python 有一定的熟练程度也是合理的。

教程应包含定期的检查点，读者可以在这些检查点上确定自己已经成功地完成了所描述的内容。每个检查点都应明确成功标准。应明确概述已知的失败案例，包括解释读者可能遇到的错误或问题。应指出因读者采取的行动而发生变化的事情，即使这些事情看似显而易见。鼓励重复，尤其是在试图建立最佳实践或通用流程时。应避免解释内部结构，也应避免解释实现相同结果的其他途径。

烘焙饼干的教程不仅仅是一份食谱。教程中的说明应该能让从未烘焙过的人（比如孩子）理解，并且需要考虑到有经验的烘焙者会认为理所当然的事情，比如如何将糖和黄油制成奶油、烤箱的预热过程，或者饼干在食用前应该冷却多长时间。教程的目的不是制作饼干，而是传授烘焙的基本知识。制作出的曲奇才是美味的食物，才会让人一开始就接受教程。

操作指南

使用指南应侧重于具体的实际案例和实际效果，而不是理论解释。与教程不同的是，指南可以假定读者对现有工具有一定的熟悉程度。读者应该能够自始至终按照指南的要求达到目标，但他们可能需要一些已有的知识才能做到这一点。指南应包括实现指南目标所需的一系列具体说明或逻辑步骤。

烹饪书中的食谱就是一个很好的指南范例。巧克力曲奇的食谱有很多，它们都有共同的特点，但任何一个具体的食谱都应该可以从头到尾照着做，并得到一致的结果。一份好的巧克力饼干食谱不会深入探讨不同类型的糖或面粉的相对优点，也不会对基本技术或流程进行详细说明；它将只包括烘焙一批饼干的配料和说明，前提是读者对烘焙有基本的了解。

主题指南

主题指南描述的是一个单独的主题或概念。它可能包括示例代码或说明，但更侧重于提供一个整体概念的高层次图景。它可能包括意见和其他观点，但应保持对指南特定主题的关注。

关于烘焙饼干的主题指南可能会深入探讨饼干作为一种烘焙产品的历史，探讨工业化工艺与自制饼干相比产生不同类型饼干的方式，或者提出将饼干纳入均衡饮食的方法。就其本身而言，如果你想烘焙曲奇饼干，这并不是一份非常有用的文档，但它可能会提供一些背景资料，使熟悉烘焙的人能够成功地定制现有的曲奇饼干食谱。

参考资料

参考文档以信息为导向，描述工具库的具体操作。参考文档通常可以从代码本身生成，但好的应用程序接口文档可能需要进一步的解释和上下文。虽然有时可能包括使用示例，但应避免详细解释。

烘焙参考指南可以描述可使用的糖的种类，并详细说明它们在烘焙中使用时的特性。它将描述有关糖的字面事实，但关于如何选择不同类型的糖的更广泛的讨论应该是如何使用或主题指南的主题。大多数包装食品上的营养信息都属于参考文献。

文件风格

BeeWare 的文档遵循文档风格指南中概述的准则。该指南包括基本样式和格式，以及拼写检查流程。它还包括各种 Markdown 语法细节，如引用链接语法、代码块使用技巧和图片处理。

提供文件

提出新的文档

提出一项新功能

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

调查研究

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

讨论想法

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

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

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

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

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

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

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

转换为正式功能请求

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

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

若您感兴趣，可开始实现新功能。

搭建开发环境

搭建开发环境

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

• Briefcase
• Toga
• Rubicon Objective-C

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

从分支工作

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

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

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

在 main 分支上工作也会给你自己完成第一个拉取请求后时带来困难。如果你想贡献第二个拉取请求，你需要有一份上游项目 main 分支的“干净”版本为基础；如果你已经从你的 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

避免范围蔓延

避免范围蔓延

当单个贡献所解决的问题或实现的功能大大超出工作开始时的预期时，就会发生 "范围蠕变"。你从一个简单的问题开始；你发现了一个密切相关的问题，并决定将该修复也包括在内；然后是第三个......不知不觉中，你的拉取请求已经关闭了 5 个问题，增加了 3 个新功能，包括数十个文件。

范围蠕变每个人都会遇到。对于经验丰富的开发人员来说，这是一个再熟悉不过的概念；我们都曾多次遇到过，并经历过随之而来的所有问题。

避免范围蠕变有非常实际的原因。贡献越大，工作就越困难。识别边缘情况或潜在问题变得更加困难，这意味着稿件的整体质量可能会下降。当评审者需要处理多个可能互不相关的背景时，评审也会变得更具挑战性。更大的贡献意味着更多的评审意见，作为贡献者，要跟踪多个评审线程可能会变得很困难。甚至您的 GitHub 体验也会受到影响–随着 PR 的大小增加，GitHub 的用户界面也会变慢，这意味着通过 GitHub 界面浏览文件和尝试留下审核意见会变得越来越困难。

任何时候，如果您发现有理由在您的贡献中添加任何不属于原始提案或错误报告明确部分的内容，您就应该考虑您是否正在走向范围蠕变。是否有两个不同的功能可以分开实现？某个功能在实现时是否会有已知的限制或错误，并在后续的拉取请求中修复该错误？错误修复的一部分是否独立于另一部分？如果可以在不改变原始贡献的情况下省略部分变更，那就应该省略。

软件开发始终是一个渐进改进的过程。每个人的贡献都应使代码库在合并后处于更好的状态，但留下错误或部分功能作为未来改进的工作也是完全可以接受的。这可能意味着将一个拉取请求分解成多个部分，以便独立审核，或者记录一个问题，以便其他人可以调查并解决问题。

限制每次投稿的范围对包括你在内的每个人都有帮助。您的审稿人，甚至您自己，都会对此表示赞赏。

建筑文件

建筑文件

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

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

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

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

实时文档预览

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

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

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

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

启动实时服务器：

macOSLinuxWindows

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

本地构建

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

生成本地构建

若想要生成本地构建：

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 目录中。

运行文档 lint

构建过程会识别 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 来帮助编写版本发布说明。当您向相关工具提交拉取请求时，需要包含变更说明——该变更说明将成为发行说明中描述变更的条目。

每个拉取请求（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 "检查发现了一个代码格式问题：

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 --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 的流程。

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