仓库管理任务

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

Tip

本节仅对少数人有用，即拥有仓库管理权限的团队成员。你大概可以跳过这部分。😉

……所以，你是 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 标题的文本，以“命令式”开头，就像下达命令一样。所以，使用 Add support for teleporting 而不是 Adding support for teleporting。
• 尝试使标题描述其实现的内容。如果是一个功能，尝试描述它，例如 Add support for teleporting 而不是 Create TeleportAdapter class。
• 不要以句号（.）结束标题。
• 当 PR 用于翻译时，以 🌐 开头，然后是 Add {language} translation for 以及翻译的文件路径。例如：

🌐 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 中的“Files changed”选项卡并检查更新的文件是否以 docs/en/docs 开头来快速检测它。文档的原始版本始终是英文，所以在 docs/en/docs 中。
• lang-all：翻译
  • 用于翻译。你通常可以通过转到 PR 中的“Files changed”选项卡并检查更新的文件是否以 docs/{some lang}/docs 开头而不是 docs/en/docs 来快速检测它。例如，docs/es/docs。
• internal：内部
  • 用于仅影响仓库管理方式的更改。例如内部依赖项的升级、GitHub Actions 或脚本的更改等。

Tip

一些工具如 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 标签。
• “admonition”部分，如 tip、info 等，没有被更改或翻译。例如：

/// tip

This is a tip.

///

看起来像这样：

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：

• 转到 Translations 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 People PRs

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

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

外部链接 PRs

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

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

检查所有这些事项并确保 PR 具有正确的标签后，你可以合并它。

Dependabot PRs

Dependabot 将创建 PR 以更新多个事物的依赖项，这些 PR 看起来都相似，但有些比其他的要敏感得多。

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

标记 GitHub Discussions 答案

当 GitHub Discussions 中的问题得到回答时，通过单击“Mark as answer”标记答案。

你可以通过 Questions that are Unanswered 过滤讨论。