儲存庫管理任務

這些是團隊成員可以執行的 FastAPI 儲存庫管理任務。

提示

本節僅對少數人，即具有儲存庫管理權限的團隊成員有用。 你可能可以跳過它。 😉

...所以，你是 FastAPI 的團隊成員？ 哇，你太酷了！ 😎

你可以像外部貢獻者一樣，透過 幫助 FastAPI - 獲得幫助 中的所有方式提供協助。 此外，還有一些任務只有你（作為團隊的一份子）才能執行。

以下是你可以執行的任務的一般說明。

非常感謝你的幫助。 🙇

保持友善

首先，保持友善。 😊

如果你被加入團隊，你可能已經非常友善了，但還是值得一提。 🤓

當事情變得困難時

當事情順利時，一切都更容易，所以不需要太多說明。 但是當事情變得困難時，以下是一些指導方針。

試著找到好的方面。 一般來說，如果人們沒有表現得不友善，即使你不同意主要的主題（討論、PR），也要試著感謝他們的努力和興趣，感謝他們對專案感興趣，或者感謝他們花時間嘗試做一些事情。

透過文字很難傳達情感，使用表情符號來幫助表達。 😅

在討論和 PR 中，很多情況下，人們會帶着他們的挫折感，並且不加掩飾地表現出來，很多時候會誇大其詞、抱怨、自以為是等等。 這真的不太好，當這種情況發生時，我們解決他們問題的優先順序會降低。 但儘管如此，還是試著深呼吸，並溫和地回覆。

盡量避免使用尖酸刻薄的諷刺或可能帶有消極攻擊性的評論。 如果有什麼不對的地方，最好直接一點（盡量溫和一點），而不是諷刺。

盡量具體和客觀，避免泛泛而談。

對於比較困難的對話，例如拒絕 PR，你可以請我（@tiangolo）直接處理。

編輯 PR 標題

• 編輯 PR 標題，以 gitmoji 中的表情符號開頭。
  • 使用表情符號字元，而不是 GitHub 代碼。 因此，使用 🐛 而不是 :bug:。 這是為了讓它在 GitHub 之外也能正確顯示，例如在發行說明中。
  • 對於翻譯，請使用 🌐 表情符號（「帶有經線的地球」）。
• 標題以動詞開頭。 例如 `新增`、`重構`、`修復` 等等。 這樣標題就會說明 PR 所執行的動作。 例如 `新增傳送支援`，而不是 `傳送功能無法運作，因此這個 PR 修復了它`。
• 將 PR 標題的文字編輯為以「祈使句」開頭，就像下達命令一樣。 因此，不要使用 `正在新增傳送支援`，而要使用 `新增傳送支援`。
• 盡量讓標題描述它所達成的目標。 如果它是一個功能，請嘗試描述它，例如 `新增傳送支援`，而不是 `建立 TeleportAdapter 類別`。
• 不要在標題結尾加上句點 (.)。
• 當 PR 是翻譯時，請以 🌐 開頭，然後是 `新增 {語言} 翻譯`，然後是翻譯後的文件路徑。 例如

🌐 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聲稱是錯誤修正，因為使用者以非預期且不支援的方式操作，但他們認為預設應該支援這種方式。許多這類PR實際上是功能新增或重構。但在某些情況下，確實是真正的錯誤。
• refactor：重構
  • 這通常是用於不改變行為的內部程式碼變更。通常是為了提高可維護性或啟用未來功能等。
• upgrade：升級
  • 這是用於升級專案的直接依賴項或額外的選用依賴項，通常在 pyproject.toml 中。因此，會影響最終使用者的項目，他們更新程式碼庫後就會收到升級。但這不是用於升級開發、測試、文件等使用的內部依賴項。這些內部依賴項，通常在 requirements.txt 檔案或GitHub Action版本中，應標記為 internal，而不是 upgrade。
• docs：文件
  • 文件中的變更。這包括更新文件、修正錯字。但不包括翻譯的變更。
  • 您通常可以透過前往PR中的「已變更檔案」頁籤，並檢查更新的檔案是否以 docs/en/docs 開頭來快速判斷。
    文件的原始版本始終是英文，因此位於 docs/en/docs 中。
• lang-all：翻譯
  • 用於翻譯。您通常可以透過前往PR中的「已變更檔案」頁籤，並檢查更新的檔案是否以 docs/{某種語言}/docs 開頭，但不是 docs/en/docs 來快速判斷。例如，docs/es/docs。
• 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 討論區，通知大家有新的翻譯需要審閱。

一旦有母語人士前來審閱 PR 並核准後，GitHub Action 就會移除 awaiting-review 標籤，並加上 approved-1 標籤。

這樣，我們就可以注意到有新的翻譯完成了，因為它們會有 approved-1 標籤。

合併翻譯 PR

對於西班牙文，由於我是母語人士且它是我熟悉的語言，我會親自進行最終審閱，並且在多數情況下會在合併 PR 之前稍微調整一下。

對於其他語言，請確認以下事項：

• 標題依照上述指示正確無誤。
• 它帶有 lang-all 和 lang-{語言代碼} 標籤。
• 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

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 討論區：

• 前往翻譯 GitHub 討論區
• 建立一個標題為「波士尼亞語翻譯」（或英文的語言名稱）的新討論區。
• 描述如下：

## 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). 🤓

將「波士尼亞語」更新為新的語言。

並將搜尋連結更新為指向將建立的新語言標籤，例如 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 看起來像這樣：👥 更新 FastAPI People。

如果測試通過，您可以立即合併它。

外部連結 PRs

當人們新增外部連結時，他們會編輯這個檔案 external_links.yml。

• 請確保新的連結位於正確的類別（例如「Podcast」）和語言（例如「日文」）中。
• 新的連結應該放在其列表的頂部。
• 連結網址應該有效（不應該返回 404 錯誤）。
• 連結的內容應該與 FastAPI 相關。
• 新增的連結應該包含以下欄位：
  • author：作者姓名。
  • link：包含內容的網址。
  • title：連結的標題（文章、Podcast 等的標題）。

確認所有這些事項並確保 PR 具有正確的標籤後，您就可以合併它。

Dependabot PRs

Dependabot 會建立 PR 來更新多個項目的依賴關係，這些 PR 看起來都很相似，但有些比其他的更為敏感。

• 如果 PR 是針對直接依賴關係，也就是 Dependabot 正在修改 pyproject.toml，**請不要合併它**。😱 讓我先檢查一下。很有可能需要一些額外的調整或更新。
• 如果 PR 更新的是內部依賴關係，例如它正在修改 requirements.txt 檔案或 GitHub Action 版本，而且測試通過，發佈說明（在 PR 中以摘要顯示）也沒有顯示任何明顯的潛在破壞性變更，您可以合併它。😎

標記 GitHub 討論的答案

當 GitHub 討論中的問題已得到解答時，請點擊「標記為答案」來標記答案。

您可以依據 問題 且 未解答 來篩選討論。