簡介¶

有興趣為社群貢獻一份心力嗎？也許您在 Django 中發現了一個想要修復的錯誤，或者想要添加一個小功能。

回饋貢獻給 Django 本身是解決您自身問題的最佳方式。一開始這可能看起來令人畏懼，但這是一條有完善文件、工具和社群支持您的成熟道路。我們將引導您完成整個過程，讓您可以通過範例學習。

行為準則¶

作為貢獻者，您可以幫助我們保持 Django 社群的開放性和包容性。請閱讀並遵守我們的 行為準則。

安裝 Git¶

在本教學中，您需要安裝 Git 才能下載 Django 的目前開發版本，並為您所做的變更產生一個分支。

要檢查您是否已安裝 Git，請在命令列中輸入 git。如果您收到訊息指出找不到此命令，則必須下載並安裝它，請參閱 Git 的下載頁面。

如果您不熟悉 Git，您可以隨時在命令列中輸入 git help 來了解更多關於其命令的資訊（一旦安裝完成）。

取得 Django 開發版本的副本¶

貢獻 Django 的第一步是取得原始程式碼的副本。首先，在 GitHub 上 Fork Django。然後，從命令列使用 cd 命令導覽至您希望 Django 本機副本所在的目錄。

使用以下命令下載 Django 原始程式碼儲存庫

$ git clone https://github.com/YourGitHubName/django.git

...\> git clone https://github.com/YourGitHubName/django.git

現在您有了 Django 的本機副本，您可以像使用 pip 安裝任何套件一樣安裝它。最方便的方法是使用虛擬環境，這是 Python 內建的一項功能，可讓您為每個專案保留一個單獨的已安裝套件目錄，以便它們彼此不干擾。

最好將所有虛擬環境保存在一個地方，例如您主目錄中的 .virtualenvs/。

透過執行以下命令建立新的虛擬環境

$ python3 -m venv ~/.virtualenvs/djangodev

...\> py -m venv %HOMEPATH%\.virtualenvs\djangodev

路徑是新環境將儲存在您電腦上的位置。

設定虛擬環境的最後一步是啟動它

$ source ~/.virtualenvs/djangodev/bin/activate

如果 source 命令不可用，您可以嘗試改用點

$ . ~/.virtualenvs/djangodev/bin/activate

每當您開啟新的終端機視窗時，都必須啟動虛擬環境。

...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat

目前已啟動的虛擬環境的名稱會顯示在命令列中，以協助您追蹤您正在使用的環境。當顯示此名稱時，您透過 pip 安裝的任何內容都將安裝在該虛擬環境中，與其他環境和全系統套件隔離。

繼續安裝先前複製的 Django 副本

$ python -m pip install -e /path/to/your/local/clone/django/

...\> py -m pip install -e \path\to\your\local\clone\django\

透過在可編輯模式下安裝，Django 的已安裝版本現在指向您的本機副本。您將立即看到您對其所做的任何變更，這對撰寫您的第一個貢獻非常有幫助。

第一次執行 Django 的測試套件¶

在為 Django 做出貢獻時，非常重要的是，您的程式碼變更不會將錯誤引入 Django 的其他區域。檢查您變更後 Django 是否仍然運作的一種方法是執行 Django 的測試套件。如果所有測試仍然通過，那麼您可以合理地確定您的變更有效並且沒有破壞 Django 的其他部分。如果您之前從未執行過 Django 的測試套件，最好先執行一次以熟悉其輸出。

在執行測試套件之前，請使用 cd tests 命令進入 Django tests/ 目錄，並透過執行以下命令安裝測試相依性

$ python -m pip install -r requirements/py3.txt

...\> py -m pip install -r requirements\py3.txt

如果您在安裝期間遇到錯誤，您的系統可能缺少一個或多個 Python 套件的相依性。請參閱失敗套件的文件或使用您遇到的錯誤訊息搜尋網路。

現在我們準備好執行測試套件了

$ ./runtests.py

...\> runtests.py 

現在請坐下來放鬆。Django 的整個測試套件有數千個測試，並且需要至少幾分鐘才能執行，具體取決於您電腦的速度。

當 Django 的測試套件正在執行時，您會看到一連串字元，代表每個測試完成時的狀態。E 表示在測試期間引發了錯誤，而 F 表示測試的斷言失敗。這兩者都被視為測試失敗。同時，x 和 s 分別表示預期失敗和略過的測試。點表示通過的測試。

略過的測試通常是由於缺少執行測試所需的外部程式庫；請參閱 執行所有測試 以取得相依性清單，並確保安裝您正在進行的變更相關測試的任何相依性（在本教學中我們不需要任何相依性）。某些測試特定於特定的資料庫後端，如果未使用該後端進行測試，則會略過。SQLite 是預設設定的資料庫後端。要使用不同的後端執行測試，請參閱 使用另一個設定模組。

一旦測試完成，您應該會收到一則訊息，告知您測試套件是否通過或失敗。由於您尚未對 Django 的程式碼進行任何變更，因此整個測試套件應該會通過。如果您遇到失敗或錯誤，請確保您已正確遵循所有先前的步驟。請參閱 執行單元測試 以取得更多資訊。

請注意，最新的 Django「main」分支可能並不總是穩定。當針對「main」進行開發時，您可以檢查 Django 的持續整合建置，以判斷失敗是否特定於您的機器，或者是否也存在於 Django 的官方建置中。如果您按一下以檢視特定建置，您可以檢視「組態矩陣」，其中顯示按 Python 版本和資料庫後端細分的失敗。

處理功能¶

在本教學中，我們將以「虛擬工單」作為案例研究。以下是虛構的詳細資訊

我們現在將實作此功能和相關的測試。

建立分支¶

在進行任何變更之前，請為該工單建立一個新分支

$ git checkout -b ticket_99999

...\> git checkout -b ticket_99999

您可以為分支選擇任何您想要的名字，例如「ticket_99999」。在此分支中所做的所有變更都將專屬於該工單，並且不會影響我們先前複製的主要程式碼副本。

為您的工單撰寫一些測試¶

在大多數情況下，要讓對 Django 的貢獻被接受，它必須包含測試。對於錯誤修復的貢獻，這表示撰寫一個回歸測試，以確保該錯誤不會在稍後重新引入 Django。回歸測試的撰寫方式應該是在錯誤仍然存在時會失敗，而在錯誤修復後會通過。對於包含新功能的貢獻，您需要包含測試，以確保新功能正常運作。它們也應該在新功能不存在時失敗，然後在實作後通過。

一個好的方法是先撰寫新的測試，然後再對程式碼進行任何變更。這種開發風格稱為測試驅動開發，並且可以應用於整個專案和單一變更。撰寫完測試後，您接著執行它們，以確保它們確實失敗（因為您尚未修復該錯誤或新增該功能）。如果您的新測試沒有失敗，您需要修復它們，讓它們失敗。畢竟，無論錯誤是否存在，都能通過的回歸測試，對於防止該錯誤在未來再次發生並沒有太大幫助。

現在是我們的實作範例。

from django.shortcuts import make_toast
from django.test import SimpleTestCase


class MakeToastTests(SimpleTestCase):
    def test_make_toast(self):
        self.assertEqual(make_toast(), "toast")

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

ImportError: cannot import name 'make_toast' from 'django.shortcuts'

為您的工單撰寫程式碼¶

接下來，我們將新增 make_toast() 函式。

導覽至 django/ 資料夾並開啟 shortcuts.py 檔案。在底部，新增

def make_toast():
    return "toast"

現在我們需要確保我們先前撰寫的測試通過，以便我們查看我們新增的程式碼是否正常運作。再次導覽至 Django tests/ 目錄並執行

$ ./runtests.py shortcuts

...\> runtests.py shortcuts

一切都應該通過。如果沒有，請確保您已正確將該函式新增至正確的檔案。

第二次執行 Django 的測試套件¶

一旦您驗證了您的變更和測試是否正確運作，最好執行整個 Django 測試套件，以驗證您的變更是否在 Django 的其他區域引入了任何錯誤。雖然成功通過整個測試套件不能保證您的程式碼沒有錯誤，但它確實有助於識別許多可能被忽略的錯誤和回歸。

若要執行整個 Django 測試套件，請 cd 至 Django tests/ 目錄並執行

$ ./runtests.py

...\> runtests.py 

撰寫文件¶

這是一個新功能，因此應該記錄下來。開啟檔案 docs/topics/http/shortcuts.txt 並在檔案末尾新增以下內容

``make_toast()``
================

.. function:: make_toast()

.. versionadded:: 2.2

Returns ``'toast'``.

由於此新功能將在即將發布的版本中推出，因此也會新增至下一個 Django 版本的發行說明中。在 docs/releases/ 中開啟最新版本的發行說明，在撰寫時為 2.2.txt。在「次要功能」標題下新增註解

:mod:`django.shortcuts`
~~~~~~~~~~~~~~~~~~~~~~~

* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.

如需有關撰寫文件的詳細資訊，包括對 versionadded 位元意義的解釋，請參閱撰寫文件。該頁面也包含如何在本機建置文件副本的說明，以便您可以預覽將產生的 HTML。

預覽您的變更¶

現在是檢閱分支中所做變更的時候了。若要暫存所有準備提交的變更，請執行

$ git add --all

...\> git add --all

然後使用以下命令顯示您目前 Django 副本（包含您的變更）與您在教學中先前最初檢視的修訂版本之間的差異

$ git diff --cached

...\> git diff --cached

使用箭頭鍵上下移動。

diff --git a/django/shortcuts.py b/django/shortcuts.py
index 7ab1df0e9d..8dde9e28d9 100644
--- a/django/shortcuts.py
+++ b/django/shortcuts.py
@@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):

     # Finally, fall back and assume it's a URL
     return to
+
+
+def make_toast():
+    return 'toast'
diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt
index 7d85d30c4a..81518187b3 100644
--- a/docs/releases/2.2.txt
+++ b/docs/releases/2.2.txt
@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the
 Minor features
 --------------

+:mod:`django.shortcuts`
+~~~~~~~~~~~~~~~~~~~~~~~
+
+* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
+
 :mod:`django.contrib.admin`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
index 7b3a3a2c00..711bf6bb6d 100644
--- a/docs/topics/http/shortcuts.txt
+++ b/docs/topics/http/shortcuts.txt
@@ -271,3 +271,12 @@ This example is equivalent to::
         my_objects = list(MyModel.objects.filter(published=True))
         if not my_objects:
             raise Http404("No MyModel matches the given query.")
+
+``make_toast()``
+================
+
+.. function:: make_toast()
+
+.. versionadded:: 2.2
+
+Returns ``'toast'``.
diff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py
new file mode 100644
index 0000000000..6f4c627b6e
--- /dev/null
+++ b/tests/shortcuts/test_make_toast.py
@@ -0,0 +1,7 @@
+from django.shortcuts import make_toast
+from django.test import SimpleTestCase
+
+
+class MakeToastTests(SimpleTestCase):
+    def test_make_toast(self):
+        self.assertEqual(make_toast(), 'toast')

當您完成預覽變更時，按下 q 鍵返回命令列。如果差異看起來沒問題，就該提交變更了。

提交變更¶

若要提交變更

$ git commit

...\> git commit

這會開啟一個文字編輯器，以輸入提交訊息。請遵循提交訊息準則並撰寫類似以下的訊息

Fixed #99999 -- Added a shortcut function to make toast.

推送提交並建立提取請求¶

提交變更後，將其傳送到您在 GitHub 上的分支（如果不同，請將「ticket_99999」替換為您的分支名稱）

$ git push origin ticket_99999

...\> git push origin ticket_99999

您可以瀏覽Django GitHub 頁面來建立提取請求。您會在「您最近推送的分支」下看到您的分支。按一下旁邊的「比較和提取請求」。

請不要在本教學中執行此操作，但是在顯示變更預覽的下一個頁面上，您會按一下「建立提取請求」。

下一步¶

恭喜，您已經學會如何向 Django 建立提取請求！您可能需要的更多進階技術的詳細資訊，請參閱使用 Git 和 GitHub。

現在您可以善用這些技能來幫助改進 Django 的程式碼庫。