撰寫良好的修補程式

寫入單獨的變更

獲得一個聲稱修復 11 個古怪問題的補丁令人煩惱，關於該補丁的討論和意見不同意它們中的 10 個算問題，或者認為這些問題中的 9 個已經用另一方式被修復了。然後，合併這一變更的人需要從成堆的原始碼中提取出單一的有趣補丁，而這樣做產生許多額外的工作。

建議每項問題修正都放在個別的修補程式或提交中，並附上自己的說明或提交訊息，明確指出修正內容，讓維護者或其他相關人員能選擇性地套用各項變更。

此外，分開提交變更也更有利於使用二分搜尋，追蹤未來的問題與回歸。

說明文件

撰寫說明文件可能很繁瑣，但仍必須有人完成。若能將說明文件與程式碼變更一併提交，事情會容易許多。請記得記錄方法、複雜的程式碼區塊及使用者可見的功能。

也參考

為 Weblate 說明文件作出貢獻

測試案例

測試可讓我們快速確認功能是否依預期運作。為維持並改善這種情況，所有新增的功能與函式都必須納入測試套件。每項新增功能至少應有一個有效測試案例，驗證其是否依說明文件運作。

也參考

Weblate 測試套件與連續整合

提交訊息

Git 提交應該遵守 Conventional Commits 規範。

類型檢查

任何新程式碼都應使用 PEP 484 型別提示。我們在使用 mypy 進行檢查（因為它有一個讓 Django 應用的型別檢查變得實際可行的 Django 外掛）。

在目前 Django 型別支援可行的範圍內，新增及變更後的程式碼不應引入新的 mypy 失敗。程式碼庫目前尚未完全涵蓋型別註解，且部分 Django 結構難以精確加上註解。因此，CI 僅對選取的模組強制執行 mypy，並另外回報其他發現。

編碼標準和程式碼檢查

程式碼應該符合 PEP 8 變成指導原則，並且應該使用 ruff 程式碼格式化器來格式化。

要檢查程式碼品質，您可以使用 ruff，其設定儲存在 pyproject.toml 中。

抑制 ruff 診斷時，請優先使用含有人類可讀規則名稱的 # ruff: ignore[rule-name]。如果不會擴大抑制範圍，請將註解放在邏輯陳述式或區塊的上一行。若移動註解會變更範圍、影響匯入排序，或插入另一個工具的 disable-next 註解與其目標程式碼之間，則應將註解保留在行內。

要落實上述規則，最簡單的方式是安裝 prek。它是 Weblate 所用 pre-commit 工具的第三方重新實作，已包含在 pyproject.toml 宣告的開發相依套件中，因此安裝這些相依套件後即可使用 prek。

要手動檢查所有檔案，請執行：

uv run prek run --all-files

如果偏好原版 pre-commit 客戶端，它使用來自 .pre-commit-config.yaml 的相同設定。

安全地編寫程式碼

編寫 Weblate 的任何代碼應該時刻記得 Security by Design Principles （由設計原理來提供安全性）。

AI 指導原則

在向專案貢獻內容時，您同意我們照原樣使用它，且您必須確保您被允許將它分發給我們。向我們提交改動代表您同意這些變更能夠並應被本專案採用，並在本專案授權下再次分發。作者應明確知道確保沒有未經許可的程式碼被提交至本專案的責任在於作者。

這無關是否使用 AI。

提交 Pull Request 時，當然應盡力確保提案品質良好並遵循我們的指引。基本原則是：若別人看得出貢獻內容是在 AI 協助下完成，您就還需要進一步修改。

本專案可以接受 AI 協助撰寫的程式碼，但程式碼仍須遵循編碼標準、清楚撰寫、具備說明文件與測試案例，並符合所有一般要求。