處理 Pull Request¶

由於 Django 託管於 GitHub 上，修補程式以 Pull Request 的形式提供。

在提交 Pull Request 時，請確保每個單獨的 commit 都符合以下描述的 commit 指南。貢獻者應盡可能提供最佳的 Pull Request。實際上，合併者（他們可能更熟悉 commit 指南）可能會決定自行將 commit 提升至標準。

您可能希望讓 Jenkins 或 GitHub Actions 使用非自動執行的 Pull Request 建置器（例如 Oracle 或 Selenium）測試 Pull Request。請參閱 CI wiki 頁面 以取得說明。

如果您發現自己更常在本地檢查 Pull Request，這個 git 別名會很有幫助

[alias]
    pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}\"

將其新增至您的 ~/.gitconfig，並將 upstream 設定為 django/django。然後您可以執行 git pr #### 以檢查對應的 Pull Request。

此時，您可以處理程式碼。使用 git rebase -i 和 git commit --amend 確保 commit 具有預期的品質水準。當您準備好時

$ # Pull in the latest changes from main.
$ git checkout main
$ git pull upstream main
$ # Rebase the pull request on main.
$ git checkout pr/####
$ git rebase main
$ git checkout main
$ # Merge the work as "fast-forward" to main to avoid a merge commit.
$ # (in practice, you can omit "--ff-only" since you just rebased)
$ git merge --ff-only pr/XXXX
$ # If you're not sure if you did things correctly, check that only the
$ # changes you expect will be pushed to upstream.
$ git push --dry-run upstream main
$ # Push!
$ git push upstream main
$ # Delete the pull request branch.
$ git branch -d pr/xxxx

...\> REM Pull in the latest changes from main.
...\> git checkout main
...\> git pull upstream main
...\> REM Rebase the pull request on main.
...\> git checkout pr/####
...\> git rebase main
...\> git checkout main
...\> REM Merge the work as "fast-forward" to main to avoid a merge commit.
...\> REM (in practice, you can omit "--ff-only" since you just rebased)
...\> git merge --ff-only pr/XXXX
...\> REM If you're not sure if you did things correctly, check that only the
...\> REM changes you expect will be pushed to upstream.
...\> git push --dry-run upstream main
...\> REM Push!
...\> git push upstream main
...\> REM Delete the pull request branch.
...\> git branch -d pr/xxxx

在變基到 main 之後，但在合併並推送到上游之前，強制推送到分支。這允許 main 和分支上的 commit 雜湊匹配，從而自動關閉 Pull Request。

如果 Pull Request 不需要合併為多個 commit，您可以使用網站上的 GitHub「合併並壓縮」按鈕。根據需要編輯 commit 訊息以符合指南，並移除自動附加到訊息第一行的 Pull Request 編號。

當重寫 Pull Request 的 commit 歷史記錄時，目標是使 Django 的 commit 歷史記錄盡可能易於使用

• 如果修補程式包含來回 commit，則將它們重寫為一個。例如，如果一個 commit 新增一些程式碼，而第二個 commit 修復第一個 commit 中引入的樣式問題，則應在合併之前壓縮這些 commit。

• 按邏輯分組將變更分隔到不同的 commit：如果您在對檔案進行其他變更的同時進行樣式清理，將變更分隔到兩個不同的 commit 將使檢查歷史記錄更容易。

• 注意 Pull Request 中上游分支的合併。

• 每次 commit 後，測試應該通過，文件應該建置。測試和文件都不應發出警告。

• 簡單且小的修補程式通常最好在一個 commit 中完成。如果合理，中等到大型工作可以拆分為多個 commit。

實用性勝過純粹性，因此由每個合併者決定要為 Pull Request 進行多少歷史記錄處理。主要重點是吸引社群、完成工作並擁有可用的 commit 歷史記錄。

Commit 指南¶

此外，在將程式碼提交到 Django 的 Git 儲存庫時，請遵循以下指南

• 永遠不要透過強制推送來變更 django/django 分支的已發佈歷史記錄。如果您絕對必須這樣做（例如，出於安全原因），請先與團隊討論情況。

• 對於任何中等到大的變更，其中「中等到大」由您判斷，請在進行變更之前，在 Django 論壇 或 django-developers 郵寄清單上提出。

  如果您提出某事但沒有人回應，請不要認為您的想法很棒並且應該立即實施，因為沒有人反對它。每個人並不總是有很多時間立即閱讀郵寄清單討論，因此您可能需要等待幾天才能獲得回應。

• 以過去式而非現在式撰寫詳細的 commit 訊息。

  • 良好：「修正 RSS API 中的 Unicode 錯誤。」

  • 不良：「修正 RSS API 中的 Unicode 錯誤。」

  • 不良：「正在修正 RSS API 中的 Unicode 錯誤。」

  commit 訊息應以最多 72 個字元的行顯示。應該有一個主旨行，以空白行分隔，然後是 72 個字元行的段落。限制是寬鬆的。對於主旨行，越短越好。在 commit 訊息的內文中，詳細資訊比少好

  Fixed #18307 -- Added git workflow guidelines.
  
  Refactored the Django's documentation to remove mentions of SVN
  specific tasks. Added guidelines of how to use Git, GitHub, and
  how to use pull request together with Trac instead.
  

  在 commit 訊息中感謝貢獻者：「感謝 A 的報告和 B 的審閱。」請酌情使用 git 的 Co-Authored-By。

• 對於分支的 commit，請在 commit 訊息前面加上分支名稱。例如：「[1.4.x] 修正 #xxxxx – 新增讀心術支援。」

• 將 commit 限制為最有意義的最細微變更。這表示使用頻繁的小 commit 而不是不頻繁的大 commit。例如，如果實作功能 X 需要對程式庫 Y 進行少量變更，請先 commit 對程式庫 Y 的變更，然後在單獨的 commit 中 commit 功能 X。這在幫助每個人追蹤您的變更方面都大有幫助。

• 將錯誤修正與功能變更分開。根據支援的版本，錯誤修正可能需要向後移植到穩定分支。

• 如果您的 commit 關閉了 Django 問題追蹤器中的工單，請以文字「已修正 #xxxxx」開始您的 commit 訊息，其中「xxxxx」是您的 commit 修復的工單編號。範例：「已修正 #123 – 新增 whizbang 功能。」我們已設定 Trac，以便任何使用該格式的 commit 訊息都會自動關閉參照的工單，並將完整的 commit 訊息張貼到該工單。

  對於好奇的人，我們正在使用 Trac 外掛程式來做到這一點。

• 如果您的 commit 參照了 Django 問題追蹤器中的工單，但沒有關閉工單，請包含「Refs #xxxxx」短語，其中「xxxxx」是您的 commit 參照的工單編號。這會自動將註解張貼到適當的工單。

• 使用此模式撰寫向後移植的 commit 訊息

  [<Django version>] Fixed <ticket> -- <description>
  
  Backport of <revision> from <branch>.
  

  例如

  [1.3.x] Fixed #17028 -- Changed diveintopython.org -> diveintopython.net.
  
  Backport of 80c0cbf1c97047daed2c5b41b296bbc56fe1d7e3 from main.
  

  wiki 上有一個 腳本來自動化此操作。

  如果 commit 修正了回歸問題，請將其包含在 commit 訊息中

  Regression in 6ecccad711b52f9273b1acb07a57d3f806e93928.
  

  （使用引入回歸問題的 commit 雜湊）。

還原 Commit¶

沒有人是完美的；錯誤將會發生。

但請盡力確保不會發生錯誤。僅僅因為我們有還原政策，並不表示您可以放鬆以達到最高品質的責任。真的：在您第一次 commit 之前，請仔細檢查您的工作，或請另一位合併者檢查！

當發現錯誤的 commit 時，請遵循這些指南

• 如果可能，請讓原始作者還原他們自己的 commit。

• 未經原始作者許可，請勿還原另一位作者的變更。

• 使用 git revert – 這將會建立反向 commit，但原始 commit 仍然是 commit 歷史記錄的一部分。

• 如果無法聯繫到原始作者（在合理的時間內 – 約一天左右）且問題嚴重 – 崩潰錯誤、主要測試失敗等 – 則在 Django 論壇 或 django-developers 郵寄清單上徵求意見，如果沒有人反對，則還原。

• 如果問題很小（例如，功能凍結後的功能 commit），請等待。

• 如果合併者和要還原者之間存在分歧，請嘗試在 Django 論壇 或 django-developers 郵寄清單上解決。如果無法達成協議，則應進行投票。

• 如果 commit 引入了已確認、已揭露的安全漏洞，則可以立即還原 commit，而無需任何人的許可。

• 如果 commit 中斷了發佈分支，發佈分支維護者可以未經許可地從發佈分支中撤回 commit。

• 如果您不小心將主題分支推送至 django/django，請將其刪除。例如，如果您執行了：git push upstream feature_antigravity，請執行反向推送：git push upstream :feature_antigravity。