使用 Git 和 GitHub¶
本節說明社群如何透過 Pull Request 為 Django 貢獻程式碼。如果您對 合併者 如何處理它們感興趣，請參閱 提交程式碼。
下面，我們將展示如何建立一個包含 Trac 工單 #xxxxx 變更的 GitHub Pull Request。透過建立一個完全準備好的 Pull Request，您將使審閱者的工作更輕鬆，這表示您的工作更有可能被合併到 Django 中。
您也可以將傳統的修補程式上傳到 Trac，但它對於審閱來說不太實用。
安裝 Git¶
Django 使用 Git 作為其原始碼控制。您可以下載 Git，但通常使用作業系統的套件管理器安裝會更容易。
Django 的 Git 儲存庫託管在 GitHub 上，建議您也使用 GitHub 進行工作。
安裝 Git 後，您應該做的第一件事是設定您的姓名和電子郵件
$ git config --global user.name "Your Real Name"
$ git config --global user.email "you@email.com"
請注意，user.name 應該是您的真實姓名，而不是您的 GitHub 暱稱。GitHub 應該知道您在 user.email 欄位中使用的電子郵件，因為這將用於將您的提交與您的 GitHub 帳戶關聯。
設定本機儲存庫¶
當您使用暱稱 “GitHub_nick” 建立您的 GitHub 帳戶，並且 fork 了 Django 的儲存庫後，請建立一個您 fork 的本機副本
git clone https://github.com/GitHub_nick/django.git
這將建立一個新的目錄 “django”，其中包含您 GitHub 儲存庫的副本。此頁面上的其餘 git 命令需要在複製的目錄中執行，所以現在切換到它
cd django
您的 GitHub 儲存庫在 Git 中將被稱為 “origin”。
您也應該將 django/django 設定為 “upstream” 遠端 (也就是告訴 git 參考的 Django 儲存庫是您 fork 的來源)
git remote add upstream https://github.com/django/django.git
git fetch upstream
您可以類似地新增其他遠端，例如
git remote add akaariai https://github.com/akaariai/django.git
處理工單¶
在處理工單時，請為工作建立一個新的分支，並將該工作基於 upstream/main
git checkout -b ticket_xxxxx upstream/main
-b 旗標會在本機為您建立一個新的分支。即使是很小的東西，也不要猶豫建立新的分支 - 這就是它們的目的。
如果相反，您正在為 1.4 分支上的修復工作，您將會執行
git checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x
假設工作在 ticket_xxxxx 分支上進行。進行一些變更並提交它們
git commit
在撰寫提交訊息時，請遵循 提交訊息指南 以簡化合併者的工作。如果您不擅長英語，請至少嘗試精確描述提交的內容。
如果您需要在您的分支上執行額外的工作，請根據需要頻繁提交
git commit -m 'Added two more tests for edge cases'
發佈工作¶
您可以透過執行以下命令在 GitHub 上發佈您的工作
git push origin ticket_xxxxx
當您前往您的 GitHub 頁面時，您會注意到已建立一個新的分支。
如果您正在處理 Trac 工單，您應該在工單中提及您的工作可以從您 GitHub 儲存庫的 ticket_xxxxx 分支取得。請包含您分支的連結。
請注意，上面的分支在 Git 術語中稱為「主題分支」。您可以透過使用 git rebase 等來自由重寫此分支的歷史記錄。其他人不應該以這樣的分支為基礎進行工作，因為當您編輯提交時，他們的複製將會損壞。
還有「公開分支」。這些是其他人應該 fork 的分支，因此這些分支的歷史記錄永遠不應該變更。公開分支的良好範例是 django/django 儲存庫中的 main 和 stable/A.B.x 分支。
當您認為您的工作已準備好被提取到 Django 中時，您應該在 GitHub 上建立一個 Pull Request。一個好的 Pull Request 表示
每次提交一個邏輯變更，並遵循 程式碼風格，
每個提交都有格式良好的訊息：一個摘要行，然後是以 72 個字元換行的段落 – 請參閱 提交指南 了解更多詳細資訊，
文件和測試 (如果需要) – 實際上總是需要測試，除了文件變更。
測試套件必須通過，並且文件必須在沒有警告的情況下建置。
建立 Pull Request 後，您應該在相關的 Trac 工單中新增一個註解，說明您做了什麼。特別是，您應該註明您執行測試的環境，例如：「所有測試在 SQLite 和 MySQL 下都通過」。
GitHub 上的 Pull Request 只有兩種狀態：開啟和關閉。處理您 Pull Request 的合併者只有兩種選擇：合併它或關閉它。因此，在程式碼準備好合併之前（或足夠接近合併者自己完成），製作 Pull Request 是沒有意義的。
變基分支¶
在上面的範例中，您建立了兩個提交，“Fixed ticket_xxxxx” 提交和 “Added two more tests” 提交。
我們不希望在您的儲存庫中保留您整個工作流程的歷史記錄。您的提交 “Added two more tests” 將會是無用的雜訊。相反地，我們寧願只有一個包含您所有工作的提交。
要重新處理您分支的歷史記錄，您可以使用互動式變基將提交合併為一個
git rebase -i HEAD~2
上面的 HEAD~2 是指兩個最新的提交的簡寫。上面的命令將開啟一個編輯器，顯示兩個提交，並以 “pick” 這個字詞作為前綴。
將第二行的 “pick” 變更為 “squash”。這將保留第一個提交，並將第二個提交合併到第一個提交中。儲存並退出編輯器。應該會開啟第二個編輯器視窗，因此您可以重新措辭提交訊息，因為它現在包含您的兩個步驟。
您也可以在變基中使用 “edit” 選項。這樣您就可以變更單個提交，例如修正文件字串中的拼寫錯誤
git rebase -i HEAD~3
# Choose edit, pick, pick for the commits
# Now you are able to rework the commit (use git add normally to add changes)
# When finished, commit work with "--amend" and continue
git commit --amend
# Reword the commit message if needed
git rebase --continue
# The second and third commits should be applied.
如果您的主題分支已經在 GitHub 上發佈，例如如果您正在進行微小的變更以考慮審閱，您將需要強制推送變更
git push -f origin ticket_xxxxx
請注意，這將重寫 ticket_xxxxx 的歷史記錄 - 如果您在 GitHub 上檢查操作前後的提交雜湊，您會注意到提交雜湊不再匹配。這是可以接受的，因為分支是一個主題分支，並且沒有人應該以它為基礎進行工作。
在上游變更之後¶
當上游 (django/django) 發生變更時，您應該變基您的工作。為此，請使用
git fetch upstream
git rebase upstream/main
工作會使用您 fork 的分支自動變基，在本例中是使用 upstream/main。
變基命令會暫時移除您所有的本機提交，套用上游提交，然後再次在工作上套用您的本機提交。
如果存在合併衝突，您將需要解決它們，然後使用 git rebase --continue。在任何時候，您都可以使用 git rebase --abort 返回到原始狀態。
請注意，您想要變基在上游，而不是合併上游。
這樣做的原因是，透過變基，您的提交將始終位於上游工作之上，而不是與上游的變更混在一起。這樣，您的分支將只包含與其主題相關的提交，這使得合併更容易。
審閱之後¶
在沒有審閱者要求變更的情況下，將任何非微量的程式碼納入核心是不尋常的。在這種情況下，最好將變更作為一個增量提交新增到您的工作中。這允許審閱者輕鬆檢查您所做的變更。
在這種情況下，請執行審閱者要求的變更。根據需要頻繁提交。在發佈變更之前，請變基您的工作。如果您新增了兩個提交，您將執行
git rebase -i HEAD~2
將第二個提交合併到第一個提交中。撰寫類似的提交訊息
Made changes asked in review by <reviewer>
- Fixed whitespace errors in foobar
- Reworded the docstring of bar()
最後，將您的工作推回您的 GitHub 儲存庫。由於您在變基期間沒有觸及公開提交，因此您應該不需要強制推送
git push origin ticket_xxxxx
您的 Pull Request 現在也應該包含新的提交。
請注意，合併者在提交程式碼時可能會將審閱提交合併到先前的提交中。
處理修補程式¶
開發人員為 Django 貢獻的一種方式是審閱修補程式。這些修補程式通常會以 GitHub 上的 Pull Request 形式存在，並且可以輕鬆整合到您的本機儲存庫中
git checkout -b pull_xxxxx upstream/main
curl -L https://github.com/django/django/pull/xxxxx.patch | git am
這將建立一個新的分支，然後將 Pull Request 中的變更套用至該分支。此時，您可以執行測試或執行您需要執行的任何其他操作來調查修補程式的品質。
有關處理 Pull Request 的更多詳細資訊，請參閱 合併者的指南。
摘要¶
如果可以的話，請在 GitHub 上工作。
透過連結到您的 GitHub 分支，在 Trac 工單上宣告您的工作。
當你準備好時，請發送 Pull Request。
盡你所能地讓你的 Pull Request 盡善盡美。
當修改你的工作內容時，使用
git rebase -i來合併提交。當上游（upstream）有變更時，執行
git fetch upstream; git rebase。
