仓库管理任务

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

Tip

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

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

您可以像外部贡献者一样，通过帮助FastAPI - 获取帮助来帮助完成所有事情。但除此之外，还有一些只有您（作为团队的一部分）才能执行的任务。

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

非常感谢您的帮助。🙇

保持友善

首先，保持友善。😊

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

当事情变得困难时

当一切顺利时，事情会更容易，所以不需要太多说明。但当事情变得困难时，这里有一些指导方针。

尝试找到好的一面。通常情况下，如果人们没有表现出不友好，即使您不同意主要话题（讨论、PR），也要感谢他们的努力和兴趣，只需感谢他们对项目的兴趣，或者感谢他们花时间尝试做些什么。

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

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

尽量避免使用苦涩的讽刺或潜在的被动攻击性评论。如果有什么不对，直接表达（尝试温和）比讽刺更好。

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

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

编辑PR标题

• 编辑PR标题以gitmoji中的表情符号开头。
  • 使用表情符号字符，而不是GitHub代码。因此，使用🐛而不是:bug:。这样，它会在GitHub之外正确显示，例如在发布说明中。
  • 对于翻译，使用🌐表情符号（“带有子午线的地球”）。
• 标题以动词开头。例如添加、重构、修复等。这样，标题将说明PR所做的动作。例如添加传送支持，而不是传送不起作用，所以这个PR修复了它。
• 编辑PR标题的文本以“命令式”开头，就像在下达命令一样。因此，与其使用添加传送支持，不如使用添加传送支持。
• 尽量使标题描述其达成的效果。如果是功能，尝试描述它，例如添加传送支持而不是创建TeleportAdapter类。
• 标题不要以句号（.）结尾。
• 当PR是翻译时，以🌐开头，然后是添加{语言}翻译，然后是翻译文件的路径。例如：

🌐 添加西班牙语翻译 `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/{某种语言}/docs 开头，而不是 docs/en/docs。例如，docs/es/docs。
• internal: 内部
  • 用于仅影响仓库管理的更改。例如内部依赖项的升级、GitHub Actions 或脚本的更改等。

Tip

一些工具，如 Dependabot，会添加一些标签，如 dependencies，但请注意，这个标签不会被 latest-changes GitHub Action 使用，因此不会用于发布说明中。请确保添加了上述标签之一。

为翻译 PR 添加标签

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

每个语言都会有一个使用语言代码的标签，如 lang-{语言代码}，例如，西班牙语的 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-{语言代码} 标签。
• 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/{语言代码}/docs/index.md 翻译文件和一个 docs/{语言代码}/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 讨论：

• 前往 Translations GitHub Discussions
• 创建一个标题为 Bosnian Translations（或该语言的英文名称）的新讨论
• 描述内容为：

## 波斯尼亚语翻译

这是跟踪文档波斯尼亚语翻译的议题。🚀

以下是需要审查的带有 `lang-bs` 标签的 PR：[待审查的 PR](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 操作将自动检测 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 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 讨论答案

当 GitHub 讨论中的问题得到解答时，请点击“标记为答案”来标记答案。

你可以按 未回答的问题 过滤讨论。