錯字修正和微不足道的文件變更¶

如果您正在修正一個非常微不足道的問題，例如變更文件中的一個字，提供修補程式的首選方式是使用 GitHub pull request，而無需 Trac ticket。

請參閱使用 Git 和 GitHub以了解更多關於如何使用 pull request 的詳細資訊。

「認領」ticket¶

在一個有來自世界各地數百位貢獻者的開源專案中，有效率地管理溝通是很重要的，這樣工作才不會重複，且貢獻者才能盡可能地發揮效率。

因此，我們的政策是讓貢獻者「認領」ticket，以便讓其他開發人員知道正在處理特定的錯誤或功能。

如果您已經確定您想要做出的貢獻，並且您有能力修復它（根據您的編碼能力、對 Django 內部結構的了解以及時間可用性來衡量），請按照下列步驟認領它

• 使用您的 GitHub 帳戶登入或在我們的 ticket 系統中建立一個帳戶。如果您有帳戶但忘記了密碼，您可以使用密碼重設頁面重設密碼。

• 如果這個問題的 ticket 尚不存在，請在我們的ticket 追蹤器中建立一個。

• 如果這個問題的 ticket 已經存在，請確保沒有其他人認領它。要做到這一點，請查看 ticket 的「擁有者」部分。如果它被分配給「nobody」，則表示它可以被認領。否則，可能有人正在處理這個 ticket。您可以尋找另一個要處理的錯誤/功能，或聯繫正在處理該 ticket 的開發人員以提供協助。如果一個 ticket 被分配了數週或數月而沒有任何活動，則可以安全地將其重新分配給您自己。

• 如果您尚未登入，請點擊 ticket 頁面左上角的「GitHub 登入」或「DjangoProject 登入」登入您的帳戶。登入後，您可以點擊頁面底部的「修改 Ticket」按鈕。

• 點擊「操作」區段中的「分配給」單選按鈕來認領 ticket。您的使用者名稱將預設填入文字框中。

• 最後，點擊底部的「提交變更」按鈕以儲存。

貢獻風格¶

請確保您所做的任何貢獻至少滿足以下要求

• 修復問題或新增功能所需的程式碼是解決方案的必要部分，但它不是唯一的部分。一個好的修復還應包括一個回歸測試，以驗證已修復的行為並防止問題再次發生。此外，如果有些 ticket 與您編寫的程式碼相關，請在測試中的某些註解中提及 ticket 號碼，以便在您的修補程式提交後，可以輕鬆地追溯相關的討論，並且 ticket 會被關閉。

• 如果程式碼新增了一個新功能，或修改了現有功能的行為，則變更也應包含文件。

當您認為您的工作已準備好接受審查時，請發送GitHub pull request。如果您因某些原因無法發送 pull request，您也可以使用 Trac 中的修補程式。使用此樣式時，請遵循以下準則。

• 以 git diff 命令傳回的格式提交修補程式。

• 使用「附加檔案」按鈕將修補程式附加到ticket 追蹤器中的 ticket。請不要將修補程式放入 ticket 描述或註解中，除非它是單行修補程式。

• 使用 .diff 副檔名命名修補程式檔案；這將讓 ticket 追蹤器套用正確的語法醒目提示，這非常有幫助。

無論您以何種方式提交您的工作，請遵循以下步驟。

• 確保您的程式碼符合我們貢獻檢查清單中的要求。

• 勾選 ticket 上的「有修補程式」方塊，並確保未勾選「需要文件」、「需要測試」和「修補程式需要改進」方塊。這會使 ticket 出現在開發儀表板上的「需要審查的修補程式」佇列中。

需要社群回饋的貢獻¶

當修補程式引入新的 Django 功能並做出某種設計決策時，需要更廣泛的社群討論。如果方法涉及棄用或引入重大變更，這一點尤其重要。

以下是從社群獲取回饋的不同方法。

棄用功能¶

Django 中程式碼可能會被棄用有幾個原因

• 如果一個功能以不向後相容的方式改進或修改，則舊功能或行為將被棄用。

• 有時候，Django 會包含一個 Python 函式庫的向後移植版本，而該函式庫並未包含在 Django 目前支援的 Python 版本中。當 Django 不再需要支援不包含該函式庫的舊版 Python 時，該函式庫將會在 Django 中被標示為已過時。

如同廢棄政策所述，Django 廢棄某項功能 (A.B) 的第一個版本，應該在調用已廢棄的功能時引發 RemovedInDjangoXXWarning (其中 XX 是該功能將被移除的 Django 版本)。假設我們有良好的測試覆蓋率，當執行測試套件並啟用警告時：python -Wa runtests.py，這些警告會轉換為錯誤。因此，當加入 RemovedInDjangoXXWarning 時，您需要消除或靜音執行測試時產生的任何警告。

第一步是移除 Django 本身對已廢棄行為的任何使用。接下來，您可以使用 ignore_warnings 裝飾器在測試中靜音實際上測試已廢棄行為的警告，無論是在測試層級還是類別層級。

1. 在特定的測試中

   from django.test import ignore_warnings
   from django.utils.deprecation import RemovedInDjangoXXWarning
   
   
   @ignore_warnings(category=RemovedInDjangoXXWarning)
   def test_foo(self): ...
   

2. 對於整個測試案例

   from django.test import ignore_warnings
   from django.utils.deprecation import RemovedInDjangoXXWarning
   
   
   @ignore_warnings(category=RemovedInDjangoXXWarning)
   class MyDeprecatedTests(unittest.TestCase): ...
   

您也應該為廢棄警告新增測試

from django.utils.deprecation import RemovedInDjangoXXWarning


def test_foo_deprecation_warning(self):
    msg = "Expected deprecation message"
    with self.assertWarnsMessage(RemovedInDjangoXXWarning, msg) as ctx:
        # invoke deprecated behavior
        ...
    self.assertEqual(ctx.filename, __file__)

務必在沒有警告參考但需要在廢棄結束時更改或移除的程式碼上方加入 RemovedInDjangoXXWarning 註解。這可能包括為了保留先前行為而新增的鉤子，或是當廢棄結束時不必要或未使用的獨立項目。例如

import warnings
from django.utils.deprecation import RemovedInDjangoXXWarning


# RemovedInDjangoXXWarning.
def old_private_helper():
    # Helper function that is only used in foo().
    pass


def foo():
    warnings.warn(
        "foo() is deprecated.",
        category=RemovedInDjangoXXWarning,
        stacklevel=2,
    )
    old_private_helper()
    ...

最後，需要更新 Django 的文件

1. 如果現有的功能有文件記錄，請使用 .. deprecated:: A.B 註解在文件中將其標記為已過時。包含簡短的描述以及關於升級路徑的說明（如果適用）。

2. 在目前版本的發行說明（docs/releases/A.B.txt）的「在 A.B 中廢棄的功能」標題下，加入已廢棄行為的描述以及升級路徑（如果適用）。

3. 在適當的版本下的廢棄時間軸（docs/internals/deprecation.txt）中加入一個條目，描述將會移除哪些程式碼。

一旦您完成這些步驟，您就完成了廢棄作業。在每個功能版本中，所有符合新版本的 RemovedInDjangoXXWarning 都會被移除。

JavaScript 貢獻¶

有關 JavaScript 貢獻的資訊，請參閱JavaScript 修補程式文件。

最佳化修補程式¶

旨在提供效能改進的修補程式應提供基準測試，顯示修補程式前後的影響，並分享供審閱者重現的命令。

貢獻檢查清單¶

請使用此檢查清單來審閱 pull request。如果您審閱的 pull request 不是您自己的，且通過以下所有標準，請將相應 Trac 工單上的「分流階段」設定為「準備簽入」。如果您在 pull request 上留下改進意見，請根據您的審閱結果勾選 Trac 工單上的適當旗標：「修補程式需要改進」、「需要文件」和/或「需要測試」。在時間和興趣允許的情況下，合併者會對「準備簽入」工單進行最終審閱，並提交變更或將其返回「已接受」狀態，以進行進一步的工作。如果您想成為合併者，對貢獻進行徹底的審閱是贏得信任的好方法。

正在尋找要審閱的修補程式嗎？請查看Django 開發儀表板的「需要審閱的修補程式」區段。

想要讓您的 pull request 獲得審閱嗎？請確保在工單上設定 Trac 旗標，以便該工單出現在該佇列中。