仓库管理任务

这些是可以通过 团队成员 执行以管理 FastAPI 仓库的任务。

提示

本节仅对少数人有用，即拥有管理仓库权限的团队成员。您可能可以跳过它。😉

…所以，您是 FastAPI 的团队成员？哇，您真是太酷了！😎

您可以通过与外部贡献者相同的方式帮助 帮助 FastAPI - 获取帮助 上的所有内容。但此外，还有一些只有您（作为团队的一部分）才能执行的任务。

以下是您可以执行的任务的一般说明。

非常感谢您的帮助。🙇

友善

首先，要友善。😊

如果您被添加到团队中，您可能非常友善，但值得一提。🤓

当事情变得困难时

当事情进展顺利时，一切都会更容易，因此不需要太多说明。但当事情变得困难时，以下是一些指导原则。

尝试找到好的方面。总的来说，如果人们没有表现出不友好，即使您不同意主要主题（讨论、PR），也要尝试感谢他们的努力和兴趣，只需感谢他们对项目的兴趣，或感谢他们投入时间尝试做一些事情。

在文本中传达情感很困难，使用表情符号来帮助。😅

在讨论和 PR 中，在许多情况下，人们会带来他们的沮丧并毫无保留地表现出来，在许多情况下夸大其词、抱怨、自以为是等。这真的不好，当这种情况发生时，我们解决他们问题的优先级会降低。但尽管如此，还是要尝试深呼吸，并温柔地回答。

尝试避免使用尖酸刻薄的讽刺或潜在的被动攻击性评论。如果有什么不对，最好是直接（尝试温柔）而不是讽刺。

尽量做到具体和客观，避免泛泛而谈。

对于更困难的对话，例如拒绝 PR，您可以请我（@tiangolo）直接处理。

编辑 PR 标题

• 编辑 PR 标题，使其以来自 gitmoji 的表情符号开头。
  • 使用表情符号字符，而不是 GitHub 代码。因此，使用 🐛 而不是 :bug:。这样，它就可以在 GitHub 之外正确显示，例如在发行说明中。
  • 对于翻译，请使用 🌐 表情符号（“带经线的地球仪”）。
• 以动词开头标题。例如 Add、Refactor、Fix 等。这样，标题就会说明 PR 所执行的操作。例如 添加对传送的支持，而不是 传送不起作用，因此此 PR 修复了它。
• 编辑 PR 标题的文本，使其以“祈使句”开头，就像发出命令一样。因此，不要使用 添加对传送的支持，而要使用 添加对传送的支持。
• 尝试使标题对它所实现的目标具有描述性。如果是功能，请尝试描述它，例如 添加对传送的支持，而不是 创建 TeleportAdapter 类。
• 不要在标题末尾添加句点（.）。
• 当 PR 用于翻译时，以 🌐 开头，然后是 添加 {语言} 翻译，然后是翻译的文件路径。例如

🌐 Add Spanish translation for `docs/es/docs/teleporting.md`

合并 PR 后，GitHub Action（latest-changes）将使用 PR 标题自动更新最新的更改。

因此，拥有一个漂亮的 PR 标题不仅在 GitHub 上看起来不错，而且在发行说明中也看起来不错。📝

为 PR 添加标签

同一个 GitHub Action latest-changes 使用 PR 中的一个标签来决定将此 PR 放入发行说明的哪个部分。

确保您使用的是 latest-changes 标签列表 中支持的标签。

• breaking: 破坏性变更
  • 如果他们在不更改代码的情况下更新版本，现有的代码将中断。这种情况很少发生，因此此标签不经常使用。
• security: 安全修复
  • 这是针对安全修复，例如漏洞。几乎不会使用它。
• feature: 功能
  • 新功能，添加对以前不存在事物的支持。
• bug: 修复
  • 某些支持的功能无法正常工作，此修复解决了该问题。许多 PR 声称是错误修复，因为用户正在以意外的方式执行不受支持的操作，但他们认为这应该是默认支持的。其中许多实际上是功能或重构。但在某些情况下，确实存在错误。
• refactor: 重构
  • 这通常用于不更改行为的内部代码更改。通常它提高了可维护性或启用了未来的功能等。
• upgrade: 升级
  • 这是针对项目直接依赖项或额外可选依赖项的升级，通常在 pyproject.toml 中。因此，会影响最终用户的事情，一旦他们更新，他们最终将在其代码库中收到升级。但这不适用于用于开发、测试、文档等的内部依赖项的升级。这些内部依赖项，通常在 requirements.txt 文件或 GitHub Action 版本中，应标记为 internal，而不是 upgrade。
• docs: 文档
  • 文档中的更改。这包括更新文档、修复错别字。但不包括对翻译的更改。
  • 您通常可以通过转到 PR 中的“已更改文件”选项卡并检查更新的文件是否以 docs/en/docs 开头来快速检测它。文档的原始版本始终为英文，因此在 docs/en/docs 中。
• lang-all: 翻译
  • 将此用于翻译。您通常可以通过转到 PR 中的“已更改文件”选项卡并检查更新的文件是否以 docs/{some lang}/docs 开头但不是 docs/en/docs 来快速检测它。例如，docs/es/docs。
• internal: 内部
  • 将此用于仅影响存储库管理方式的更改。例如内部依赖项的升级、GitHub Actions 或脚本的更改等。

提示

某些工具（如 Dependabot）会添加一些标签，例如 dependencies，但请记住，此标签未被 latest-changes GitHub Action 使用，因此不会在发行说明中使用。请确保添加了上述标签之一。

为翻译 PR 添加标签

当有翻译的 PR 时，除了添加 lang-all 标签外，还要添加语言标签。

每个语言都会有一个标签，使用语言代码，例如 lang-{lang code}，例如，西班牙语为 lang-es，法语为 lang-fr 等。

• 添加特定的语言标签。
• 添加标签 awaiting-review。

标签 awaiting-review 是特殊的，仅用于翻译。一个 GitHub Action 将检测到它，然后它将读取语言标签，并更新管理该语言翻译的 GitHub Discussions 以通知人们有新的翻译需要审查。

一旦母语人士来审查 PR 并批准它，GitHub Action 将出现并删除 awaiting-review 标签，并添加 approved-1 标签。

这样，我们就可以注意到何时有新的翻译准备就绪，因为它们具有 approved-1 标签。

合并翻译 PR

对于西班牙语，作为母语人士，它是一种与我接近的语言，我将亲自对其进行最终审查，并且在大多数情况下会在合并之前稍微调整一下 PR。

对于其他语言，请确认

• 标题是否按照上述说明正确。
• 它是否具有标签 lang-all 和 lang-{lang code}。
• PR 是否只更改了一个 Markdown 文件以添加翻译。
  • 或者在某些情况下，最多两个文件，如果它们很小，对于同一种语言，并且人们审查了它们。
  • 如果这是该语言的第一个翻译，它将有额外的 mkdocs.yml 文件，对于这些情况，请遵循以下说明。
• PR 没有添加任何其他或多余的文件。
• 翻译似乎与原始英文文件具有相似的结构。
• 翻译似乎没有更改原始内容，例如明显的其他文档部分。
• 翻译没有使用不同的 Markdown 结构，例如在原始文件没有的情况下添加 HTML 标签。
• “警告”部分，如 tip、info 等，不会更改或翻译。例如

/// tip

This is a tip.

///

看起来像这样

提示

这是一个提示。

…它可以翻译为

/// tip

Esto es un consejo.

///

…但需要保留完全相同的 tip 关键字。如果它被翻译成 consejo，就像

/// consejo

Esto es un consejo.

///

它将样式更改为默认样式，它将看起来像

/// consejo

Esto es un consejo.

///

这些不需要翻译，但如果翻译了，则需要写成

/// tip | "consejo"

Esto es un consejo.

///

看起来像

"consejo"

Esto es un consejo.

第一个翻译 PR

当某个语言有第一个翻译时，它将有一个 docs/{lang code}/docs/index.md 翻译文件和一个 docs/{lang code}/mkdocs.yml。

例如，对于波斯尼亚语，它将是

• docs/bs/docs/index.md
• docs/bs/mkdocs.yml

mkdocs.yml 文件将仅包含以下内容

INHERIT: ../en/mkdocs.yml

语言代码通常在 ISO 639-1 语言代码列表 中。

无论如何，语言代码都应在文件 docs/language_names.yml 中。

还没有该语言代码的标签，例如，如果它是波斯尼亚语，则不会有 lang-bs。在创建标签并将其添加到 PR 之前，请创建 GitHub Discussions

• 转到 翻译 GitHub Discussions
• 创建一个新的讨论，标题为 Bosnian Translations（或英文的语言名称）
• 描述

## Bosnian translations

This is the issue to track translations of the docs to Bosnian. 🚀

Here are the [PRs to review with the label `lang-bs`](https://github.com/fastapi/fastapi/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+label%3Alang-bs+label%3A%22awaiting-review%22). 🤓

将“波斯尼亚语”更新为新语言。

并将搜索链接更新为指向将创建的新语言标签，例如 lang-bs。

创建并将标签添加到刚刚创建的新讨论中，例如 lang-bs。

然后返回到 PR，并添加标签，例如 lang-bs、lang-all 和 awaiting-review。

现在 GitHub action 将自动检测标签 lang-bs 并在该讨论中发布此 PR 正在等待审查。

审查 PR

如果 PR 没有解释它做了什么或为什么，请索取更多信息。

PR 应该有一个它正在解决的特定用例。

• 如果 PR 是针对功能的，则应该有文档。
  • 除非这是一个我们想要阻止的功能，例如我们不希望用户使用的极端情况的支持。
• 文档应包含源示例文件，而不是在 Markdown 中直接编写 Python。
• 如果源示例文件可以对 Python 3.8、3.9、3.10 具有不同的语法，则应该有该文件的不同版本，并且应该在文档中的选项卡中显示它们。
• 应该有测试测试源示例。
• 在应用 PR 之前，新的测试应该失败。
• 应用 PR 后，新的测试应该通过。
• 覆盖率应保持在 100%。
• 如果您认为 PR 有意义，或者我们讨论过并认为它应该被接受，您可以在 PR 的顶部添加提交来调整它，添加文档、测试、格式、重构、删除额外文件等。
• 随时在 PR 中发表评论以索取更多信息、建议更改等。
• 一旦您认为 PR 已准备好，请将其移动到内部 GitHub 项目中供我审查。

FastAPI 人员 PR

每个月，一个 GitHub Action 都会更新 FastAPI 人员数据。这些 PR 看起来像这样：👥 更新 FastAPI 人员。

如果测试通过，您可以立即合并它。

外部链接 PR

当人们添加外部链接时，他们会编辑此文件 external_links.yml。

• 确保新链接位于正确的类别（例如“播客”）和语言（例如“日语”）中。
• 新链接应位于其列表的顶部。
• 链接 URL 应有效（不应返回 404）。
• 链接的内容应与 FastAPI 相关。
• 新添加的内容应具有以下字段
  • author: 作者姓名。
  • link: 内容的 URL。
  • title: 链接的标题（文章、播客等的标题）。

检查完所有这些内容并确保 PR 具有正确的标签后，您可以合并它。

Dependabot PR

Dependabot 将创建 PR 以更新多项内容的依赖项，并且这些 PR 看起来都相似，但有些比其他的要微妙得多。

• 如果 PR 是针对直接依赖项的，因此，Dependabot 正在修改 pyproject.toml，**请不要合并它**。😱 请先让我检查一下。很有可能需要一些额外的调整或更新。
• 如果 PR 更新了其中一个内部依赖项，例如它正在修改 requirements.txt 文件或 GitHub Action 版本，如果测试通过，发行说明（在 PR 中的摘要中显示）没有显示任何明显的潜在破坏性更改，您可以合并它。😎

标记 GitHub Discussions 答案

当 GitHub Discussions 中的问题得到解答时，请通过单击“标记为答案”来标记答案。

您可以按 未回答的 的 问题 筛选讨论。