仓库管理任务

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

提示

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

……所以，你是 FastAPI 团队成员？哇，你真酷！😎

你可以像外部贡献者一样，通过 帮助 FastAPI - 获取帮助 中的所有方式提供帮助。但此外，还有一些只有你（作为团队成员）才能执行的任务。

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

非常感谢你的帮助。🙇

友善待人

首先，要友善。😊

如果你被加入了团队，你可能已经非常友善了，但这仍然值得一提。🤓

遇到困难时

顺风顺水时，一切都更容易，所以不需要太多说明。但当事情变得困难时，以下是一些指导方针。

尝试寻找积极的一面。一般来说，如果人们没有表现出不友善，即使你不同意主要议题（讨论、PR），也请感谢他们的努力和兴趣，感谢他们对项目感兴趣，或感谢他们花时间尝试做某事。

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

在讨论和 PR 中，很多情况下，人们会 unfiltered 地表达他们的挫败感，很多时候会夸大其词、抱怨、自以为是等等。这真的很不友好，当这种情况发生时，会降低我们解决他们问题的优先级。但即便如此，也要尝试深呼吸，并温柔地回答。

尽量避免使用尖酸刻薄的讽刺或潜在的被动攻击性评论。如果有什么不对劲，直接指出（并尽量温和）总比讽刺要好。

尽量具体和客观，避免概括性言论。

对于更困难的对话，例如拒绝一个 PR，你可以直接让我（@tiangolo）来处理。

编辑 PR 标题

• 编辑 PR 标题，使其以 gitmoji 中的一个表情符号开头。
  • 使用表情符号字符，而不是 GitHub 代码。例如，使用 🐛 而不是 :bug:。这样可以确保它在 GitHub 之外也能正确显示，例如在发布说明中。
  • 对于翻译，使用 🌐 表情符号（“带经纬线的地球”）。
• 标题以动词开头。例如 Add（添加）、Refactor（重构）、Fix（修复）等。这样标题会说明 PR 执行的动作。例如 Add support for teleporting（添加对瞬移的支持），而不是 Teleporting wasn't working, so this PR fixes it（瞬移不工作，所以这个 PR 修复了它）。
• 编辑 PR 标题的文本，使其以“祈使语气”开头，如同发出命令。所以，不要使用 Adding support for teleporting（正在添加对瞬移的支持），而要使用 Add support for teleporting（添加对瞬移的支持）。
• 尝试使标题描述其所实现的内容。如果是一个功能，尝试描述它，例如 Add support for teleporting（添加对瞬移的支持），而不是 Create TeleportAdapter class（创建 TeleportAdapter 类）。
• 标题不要以句号（.）结尾。
• 当 PR 是翻译时，以 🌐 开头，然后是 Add {language} translation for，接着是翻译后的文件路径。例如：

🌐 Add Spanish translation for `docs/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 修复了它。有许多 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/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.

///

看起来像这样：

提示

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 Discussion：

• 前往 翻译 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). 🤓

将“Bosnian”更新为新语言。

并更新搜索链接，使其指向将要创建的新语言标签，例如 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 讨论的答案

当 GitHub Discussions 中的问题得到解答后，点击“标记为答案”来标记该答案。

你可以按**未解答的问题**来筛选讨论。