代码仓库管理任务

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

提示

本节内容仅对少数人（拥有代码仓库管理权限的团队成员）有用。你大概可以跳过它。😉

……所以，你是 FastAPI 团队的一员？哇，你太酷了！😎

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

以下是你可执行任务的通用说明。

非常感谢你的帮助。🙇

保持友善

首先，要保持友善。😊

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

当事情变得困难时

当事情进展顺利时，一切都比较容易，所以不需要太多指导。但当事情变得困难时，这里有一些指导方针。

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

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

在讨论和 PR 中，很多时候人们会毫无过滤地表达他们的挫败感，很多时候会夸大、抱怨、自以为是等。这确实不太好，当这种情况发生时，我们解决他们问题的优先级就会降低。但尽管如此，还是要努力深呼吸，并在回答时保持温和。

尽量避免使用尖刻的讽刺或潜在的被动攻击性评论。如果有什么问题，最好直接说出来（尽量温和），而不是讽刺。

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

对于更困难的对话，例如拒绝一个 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 声称是 bug 修复，因为用户以一种非预期的方式使用了不支持的功能，但他们认为这应该是默认支持的。其中许多实际上是功能或重构。但在某些情况下，确实存在 bug。
• refactor: 重构
  • 这通常用于对内部代码的更改，这些更改不改变行为。通常它会提高可维护性，或为未来的功能做准备等。
• upgrade: 升级
  • 这用于升级项目的直接依赖项，或额外的可选依赖项，通常在 pyproject.toml 文件中。所以，这些会影响最终用户，他们更新后会在自己的代码库中收到升级。但这不包括用于开发、测试、文档等的内部依赖项的升级。那些内部依赖项，通常在 requirements.txt 文件或 GitHub Action 版本中，应该标记为 internal，而不是 upgrade。
• docs: 文档
  • 文档中的更改。这包括更新文档、修复拼写错误。但不包括对翻译的更改。
  • 你通常可以通过进入 PR 的“Files changed”（文件变更）选项卡，检查更新的文件是否以 docs/en/docs 开头来快速识别。文档的原始版本总是英文的，所以在 docs/en/docs 中。
• lang-all: 翻译
  • 用这个标签来标记翻译。你通常可以通过进入 PR 的“Files changed”（文件变更）选项卡，检查更新的文件是否以 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 标签的地方添加了 HTML 标签。
• “admonition” 部分，如 tip、info 等，没有被更改或翻译。例如：

/// tip

This is a tip.

///

看起来像这样

提示

这是一个提示。

……它可以被翻译为

/// tip

Esto es un consejo.

///

……但需要保留确切的 tip 关键字。如果它被翻译成 consejo，像这样：

/// consejo

Esto es un consejo.

///

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

/// consejo

这是一个建议。

///

这些不必翻译，但如果翻译了，它们需要写成

/// tip | consejo

Esto es un consejo.

///

看起来像这样

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。

创建标签并将其添加到刚刚创建的新 Discussion 中，如 lang-bs。

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

现在 GitHub action 会自动检测到 lang-bs 标签，并在该 Discussion 中发帖，说明此 PR 正在等待审查。

审查 PR

如果一个 PR 没有解释它做了什么或为什么这么做，请要求提供更多信息。

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

• 如果 PR 是关于一个功能，它应该有文档。
  • 除非是我们不鼓励使用的功能，比如对我们不希望用户使用的极端情况的支持。
• 文档应该包含一个源示例文件，而不是直接在 Markdown 中编写 Python。
• 如果源示例文件可以有适用于 Python 3.8、3.9、3.10 的不同语法，那么应该有不同版本的文件，并且它们应该在文档中以选项卡的形式显示。
• 应该有测试来测试源示例。
• 在应用 PR 之前，新的测试应该会失败。
• 应用 PR 后，新的测试应该会通过。
• 覆盖率应保持在 100%。
• 如果你认为 PR 是合理的，或者我们讨论过并认为应该接受它，你可以在 PR 的基础上添加提交来调整它，比如添加文档、测试、格式化、重构、删除多余文件等。
• 随时可以在 PR 中评论以要求更多信息、建议更改等。
• 一旦你认为 PR 准备好了，就将它移动到内部的 GitHub 项目中，以便我进行审查。

FastAPI People PR

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

如果测试通过，你可以直接合并它。

外部链接 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 中的问题得到回答后，通过点击“标记为答案”来标记该答案。

你可以通过未回答的问题来筛选讨论。