跳到内容

仓库管理任务

这些是由 团队成员 执行的 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 标题文本应使用“祈使语气”，就像下达命令一样。因此，不要使用 Adding support for teleporting，而应使用 Add support for teleporting。
  • 标题要尽可能描述清楚它实现了什么。如果是功能，请尝试描述它，例如 Add support for teleporting 而不是 Create TeleportAdapter class。
  • 标题结尾不要加句号 (.)。
  • 当 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: 重大变更 (Breaking Changes)
    • 如果用户在不修改代码的情况下更新版本，现有代码将会崩溃。这种情况很少发生，因此该标签不常使用。
  • security: 安全修复 (Security Fixes)
    • 用于安全漏洞修复。几乎从不使用。
  • feature: 功能 (Features)
    • 新功能，增加以前不存在的支持。
  • bug: 修复 (Fixes)
    • 原本支持的功能无法正常工作，通过此项进行修复。许多 PR 自称是 bug 修复，因为用户以一种未被支持的意外方式操作，但他们认为这应该是默认支持的。其中许多实际上是功能或重构。但在某些情况下，确实存在 bug。
  • refactor: 重构 (Refactors)
    • 通常用于不改变行为的内部代码变更。通常是为了提高可维护性，或支持未来功能等。
  • upgrade: 升级 (Upgrades)
    • 用于升级项目的直接依赖项或额外的可选依赖项，通常在 pyproject.toml 中。这些变动会影响最终用户，当用户更新版本时，他们会在代码库中收到升级。但这不适用于开发、测试、文档等内部依赖的升级。那些内部依赖或 GitHub Action 版本应标记为 internal，而不是 upgrade。
  • docs: 文档 (Docs)
    • 文档的变更。包括更新文档、修正拼写错误。但不包括翻译变更。
    • 你通常可以通过访问 PR 中的“Files changed”（文件变更）选项卡，查看更新的文件是否以 docs/en/docs 开头来快速识别。文档的原始版本始终是英语，即 docs/en/docs。
  • lang-all: 翻译 (Translations)
    • 用于翻译。你通常可以通过访问 PR 中的“Files changed”（文件变更）选项卡，查看更新的文件是否以 docs/{某种语言}/docs 开头，但不以 docs/en/docs 开头来快速识别。例如，docs/docs。
  • internal: 内部 (Internal)
    • 用于仅影响仓库管理方式的变更。例如内部依赖的升级、GitHub Actions 或脚本的变更等。

提示

像 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

翻译由 LLM 和脚本自动生成。

有一个可以手动运行的 GitHub Action 用于添加或更新某种语言的翻译：translate.yml。

对于这些语言翻译 PR，请确认：

  • PR 是自动生成的（由 @tiangolo 创建），而不是由其他用户制作的。
  • 它带有 lang-all 和 lang-{语言代码} 标签。

对于更新特定语言 LLM 提示词的 PR，请确认：

  • PR 带有 lang-all 和 lang-{语言代码} 标签。
  • 它至少由一名母语人士批准。
  • 在某些情况下，你可能需要用新的提示词翻译几页内容，以确保其按预期工作。

如果 PR 符合上述条件，你可以合并它。😎

审查 PR

  • 如果 PR 没有解释其作用或原因，但看起来可能有用，请索取更多信息。否则，请随意关闭它。

  • 如果 PR 看起来是垃圾信息、毫无意义、仅为了更改统计数据（为了显示为“贡献者”）或类似内容，你可以直接将其标记为 invalid，它会自动关闭。

  • 如果 PR 看起来是 AI 生成的，且审查它的时间比编写提示词的时间还长，请将其标记为 maybe-ai，它会自动关闭。

  • PR 应该有它要解决的特定用例。

  • 如果是功能性 PR，它应该包含文档。

    • 除非它是我们想要劝阻的功能，例如我们不希望用户使用的边缘案例支持。
  • 文档应包含源代码示例文件，不要直接在 Markdown 中编写 Python 代码。
  • 如果源代码示例文件在不同 Python 版本下有不同语法，则应有不同版本的文件，并应在文档的选项卡中展示。
  • 应该有测试来验证源代码示例。
  • 在应用 PR 之前，新测试应该失败。
  • 应用 PR 后，新测试应该通过。
  • 代码覆盖率应保持在 100%。
  • 如果你认为 PR 有意义，或者经过讨论认为应该接受，你可以在 PR 之上添加提交来对其进行微调，例如添加文档、测试、格式化、重构、删除多余文件等。
  • 欢迎在 PR 中发表评论以索取更多信息、建议更改等。
  • 一旦你认为 PR 已准备就绪，将其移至内部 GitHub 项目中，以便我进行审查。

FastAPI People PR

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

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

Dependabot PR

Dependabot 会创建 PR 来更新各种依赖项，这些 PR 看起来都很相似，但有些远比其他的棘手。

  • 如果 PR 是针对直接依赖项的，即 Dependabot 正在修改 pyproject.toml 中的主要依赖项，不要合并它。😱 请让我先查看一下。很有可能需要进行一些额外的调整或更新。
  • 如果 PR 更新的是内部依赖项（例如 pyproject.toml 中的 dev 组），或者 GitHub Action 版本，且测试通过，且发布说明（在 PR 摘要中显示）没有显示任何明显的潜在重大变更，你可以合并它。😎

标记 GitHub Discussions 答案

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

你可以通过 Unanswered（未解答）的 Questions（问题） 过滤讨论。