添加文档

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

文档表单

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

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

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

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

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

教程

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

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

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

操作指南

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

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

主题指南

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

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

参考资料

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

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

文件风格

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

提供文件

提出新的文档

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

调查研究

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

讨论想法

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

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

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

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

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

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

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

转换为正式功能请求

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

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

搭建开发环境

要为 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

避免范围蔓延

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

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

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

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

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

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

建筑文件

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