為了幫助我們理解文件中後續各種指南的原因，首先讓我們瞭解一下這個專案典型的補丁系列是如何產生生命週期的。

在接下來的部分中，列出了許多技術和約定，以幫助你的補丁在這種生命週期中得到有效審查。

作為初步步驟，你必須首先為你的工作選擇一個起點。通常這意味著選擇一個分支，儘管從技術上講，它實際上是一個特定的提交（通常是分支的 HEAD 或尖端）。

有幾個重要的分支需要注意。即，有四個整合分支，如 gitworkflows[7] 中所述。

列表中較早的分支通常是比它們靠前的分支的後代。例如，maint 比 master 是一個“更老”的分支，因為 master 通常在 maint 之上包含提交。

還有“主題”分支，它們包含其他貢獻者的工作。主題分支由 Git 維護者（在其 fork 中）建立，以組織郵件列表上當前傳入的貢獻集，並在定期的“What’s cooking in git.git”公告中列出。要找到主題分支的尖端，請執行 git log --first-parent master..seen 並查詢合併提交。此提交的第二個父提交是主題分支的尖端。

選擇正確起點的指導原則是：一般來說，始終將你的工作建立在你所做的更改相關的最舊整合分支之上（參見 gitworkflows[7] 中的“向上合併”）。這個原則意味著在絕大多數情況下，新工作的起點應該是 _maint_ 或 _master_ 的最新 HEAD 提交，具體取決於以下情況：

這也意味著，如果你想讓你的工作有機會升級到 master，那麼 _next_ 或 _seen_ 不適合作為你工作的起點。它們根本不是為作為新工作的基礎而設計的；它們只是為了確保正在進行的主題能協同工作。這就是為什麼 _next_ 和 _seen_ 經常與郵件列表上的傳入補丁重新整合並強制推送以替換它們以前的版本。一個字面上建立在 _next_ 之上的主題，在沒有將 _next_ 中的所有其他尚未準備好的主題拖入的情況下，無法合併到 _master_。

例如，如果你正在進行跨整個系統的更改，而其他人也在進行他們自己的跨整個系統的更改，那麼你的工作可能會與其他人的工作產生嚴重的重疊。這種情況可能會誘使你使用 _next_ 作為你的起點（因為它包含了其他人的工作），但這樣做意味著你不僅依賴於其他人的工作，還依賴於已經整合到 _next_ 中的來自其他貢獻者的所有其他隨機事物。並且一旦 _next_ 被新版本更新，你的所有工作都將需要重新定位，以便維護者可以乾淨地應用它們。

在絕對必須依賴 _next_ 中已存在但 _master_ 中不存在的少數主題分支的真正特殊情況下，你可能想透過 fork _master_ 並將所需的主題分支合併到其中來建立自己的自定義基礎分支。然後你可以在這個基礎分支之上工作。但請記住，這個基礎分支只會對你個人可見。所以當你準備將你的補丁傳送到列表時，請務必在你的封面信中說明你是如何建立它的。這個關鍵資訊將允許其他人復現你的基礎分支，以便他們可以試用你的工作。

最後，請注意，系統的某些部分有專門的維護者，他們有自己的獨立原始碼倉庫（參見下面的“子系統”部分）。

除非你的補丁非常微小，否則你不應該傳送一個在你的工作樹和你的提交頭之間生成的補丁。相反，始終使用完整的提交訊息建立一個提交，並從你的倉庫生成一系列補丁。這是一個很好的習慣。

對更改提供足夠詳細的解釋，以便人們能夠判斷它是否是一件好事，而無需閱讀實際的補丁文字來確定程式碼在多大程度上實現瞭解釋的承諾。

如果你的描述開始變得太長，這表明你可能需要將你的提交分成更細粒度的部分。也就是說，能夠幫助審查者檢查補丁並使未來的維護者理解程式碼的補丁是最漂亮的。主題總結了要點的描述，解釋了更改的動機、所採取的方法，以及如果相關，與先前版本有何實質性不同，這些都是很好的內容。

確保你為要修復的錯誤提供了測試。有關指導，請參見 t/README。

新增新功能時，確保你有新的測試來表明功能在應該觸發時觸發了新行為，並且在不應該觸發時沒有觸發。在任何程式碼更改後，確保整個測試套件都能透過。修復錯誤時，確保你有新的測試，如果有人意外破壞了你修復的內容，這些測試會失敗，以避免迴歸。另外，嘗試將你的工作合併到 _next_ 和 _seen_ 中，並確保測試仍然透過；其他人仍在進行中的主題可能與你正在進行的主題產生意外的互動。

推送到 https://github.com/git/git 的 fork 將使用他們的 CI 整合在 Linux、Mac 和 Windows 上測試你的更改。有關詳細資訊，請參閱 GitHub CI 部分。

不要忘記更新文件以描述已更新的行為，並確保生成的文件集格式正確（嘗試 Documentation/doc-diff 指令碼）。

我們目前在拼寫和語法上混合了美式和英式英語的規範，這有些不幸。然而，一個巨大的補丁，為了糾正不一致性而觸及了所有地方的檔案，是不會受歡迎的。這種補丁可能與其他更改產生的潛在衝突是不值得的。我們寧願透過小的、易於理解的補丁，作為做一些附近實際工作（例如，為了清晰而重寫一段話，同時將英式拼寫轉換為美式拼寫）的副作用，來逐漸調和不一致性，偏向美式英語。明顯的拼寫錯誤（“teh → the”）則更受歡迎，最好作為獨立於其他文件更改的補丁提交。

哦，還有一件事。我們對空格很挑剔。確保你的更改不會觸發 templates/hooks--pre-commit 中提供的示例預提交鉤子的錯誤。為了幫助確保這種情況不會發生，在提交更改之前，請執行 git diff --check。

解釋你更改的日誌訊息與更改本身一樣重要。你的程式碼可能寫得很清楚，有程式碼內註釋來充分解釋它如何與周圍的程式碼協同工作，但那些將來需要修復或增強你的程式碼的人需要知道你的程式碼**為什麼**這樣做，有幾個原因：

你的日誌訊息的目標是傳達你更改背後的**原因**，以幫助未來的開發者。審查者還將確保你提議的日誌訊息能夠很好地實現這一目的。

提交訊息的第一行應該是簡短的描述（50 個字元是軟限制，參見 git-commit[1] 的 DISCUSSION），並且應省略句號。在大多數情況下，還習慣性地在第一行前面加上“area: ”，其中 area 是一個檔名或識別符號，表示要修改的程式碼的通用區域，例如：

如果不確定使用哪個識別符號，請執行 git log --no-merges 檢視你正在修改的檔案，以瞭解當前的約定。

“area:”字首後面的標題行省略了末尾的句號，並且其首個單詞不首字母大寫（不首字母大寫僅適用於標題中“area:”字首之後的單詞），除非有其他原因需要首字母大寫。例如，“doc: clarify…​”，而不是“doc: Clarify…​”，或“githooks.txt: improve…​”，而不是“githooks.txt: Improve…​”。但“refs: HEAD is also treated as a ref”是正確的，因為即使在句子中間，我們也全部大寫 HEAD。

正文應提供有意義的提交訊息，該訊息

描述現狀的問題陳述以現在時態書寫。寫“程式碼在給定輸入 Y 時執行 X”，而不是“程式碼過去在給定輸入 X 時執行 Y”。你不必說“目前”——問題陳述中的現狀是關於**沒有**你更改的程式碼，按照專案約定。

用命令式語氣描述你的更改，例如，“make xyzzy do frotz”而不是“[This patch] makes xyzzy do frotz”或“[I] changed xyzzy to do frotz”，就像你正在給程式碼庫下達命令來改變其行為一樣。儘量確保你的解釋無需外部資源就能理解。不要提供指向郵件列表存檔的 URL，而是總結討論的相關要點。

你可能想引用歷史記錄中“更穩定”部分（即在 _maint_、_master_ 和 _next_ 等分支上）的另一個提交，有幾個原因：

當你引用一個更穩定分支（如 _master_、_maint_ 和 _next_）上的提交時，請使用“縮寫雜湊（主題，日期）”格式，如下所示：

gitk 的“複製提交引用”命令可以用於獲取此格式（主題用雙引號括起來），或者呼叫 git show：

或者，在不支援 --pretty=reference 的舊版本 Git 上：

為了改進跟蹤誰做了什麼，我們要求你透過“簽署”你的補丁來認證你編寫了該補丁或有權在與我們相同的許可證下分發它。沒有簽署，我們就無法接受你的補丁。

如果你（並且僅當你）認證以下 D-C-O

你會在你的提交中新增一個“Signed-off-by”尾部，它看起來像這樣：

如果你使用 -s 選項執行 git-commit 命令，Git 會自動新增這一行。

請注意，根據上述 D-C-O 規則，在轉發展其他人的補丁時，你也可以新增自己的 Signed-off-by 尾部。事實上，我們鼓勵這樣做。不要忘記在正文中新增一個“From: ”行，以正確地將更改歸因於其真正的作者（參見上面的 (2)）。

此程式最初來自 Linux 核心專案，因此我們的規則與之非常相似，但簽署你的補丁的確切含義因專案而異，所以可能與你習慣的專案不同。

請在 Signed-off-by 尾部使用已知的身份，因為我們無法接受匿名貢獻。使用你真實姓名的某種形式很常見，但並非強制要求。我們認識到有些貢獻者對此感到不舒服，或者更喜歡以化名或首選名稱貢獻，我們可以接受你的補丁，只要你使用的姓名和電子郵件是獨特、可識別且不具誤導性的。

此政策的目標是使我們擁有足夠的資訊，以便在出現關於你貢獻的問題時能夠聯絡到你。

如果你願意，可以在末尾新增額外的尾部：

雖然在情況需要時你也可以建立自己的尾部，但我們鼓勵你使用上面突出顯示的此專案中的常用尾部之一。

只將尾部的第一個字母大寫，即偏好“Signed-off-by”而不是“Signed-Off-By”，以及“Acked-by:”而不是“Acked-By”。

開發者起源證明要求貢獻者證明他們知道其貢獻的來源，並且他們有權在專案的許可證下提交它。當提交大量由 AI 工具生成的內容時，尚不清楚這是否能在法律上滿足要求。

AI 生成內容的另一個問題是，AI 仍然經常會產生幻覺或僅僅產生不好的程式碼、提交訊息、文件或輸出，即使你指出了它們的錯誤。

為了避免這些問題，我們將拒絕任何看起來是 AI 生成的、聽起來過於正式或冗長、看起來像 AI 垃圾、表面上看起來不錯但沒有意義，或者傳送者不理解或無法解釋的內容。

我們強烈建議謹慎負責地使用 AI 工具。

貢獻者透過使用 AI 來指導和幫助他們逐步自行完成解決方案，而不是要求一個他們然後大部分複製貼上的完整解決方案，從而受益更多。他們還可以使用 AI 來幫助除錯，或者檢查明顯的錯誤、可以改進的地方、不符合我們的風格、指南或反饋的地方，然後再發送給我們。

基於 Git 的 diff 工具生成 unidiff，這是首選格式。

如果你的補丁涉及檔案重新命名，你無需擔心使用 git diff 或 git format-patch 的 -M 選項。接收方可以很好地處理它們。

請確保你的補丁不添加註釋掉的除錯程式碼，或包含任何與你的補丁試圖達成的目標無關的額外檔案。生成補丁後，請務必檢查以確保準確性。在傳送之前，請確保它能幹淨地應用到你在“選擇起點”部分選擇的起點上。

在修改您的補丁時，承認與其他正在進行的開發主題可能發生衝突的可能性非常重要。為了有效地處理這些潛在的衝突，請遵循下面概述的推薦步驟

（Johannes Schindelin）

（Linus Torvalds）

（Daniel Barkalow）

請參閱git-format-patch[1] 的MUA-SPECIFIC HINTS 部分。

在*Summary*緩衝區中的“|”可以將當前訊息透過管道傳輸到外部程式，這是驅動git am的便捷方法。但是，如果訊息是 MIME 編碼的，則透過管道傳輸到程式的是您在*Article*緩衝區中解開 MIME 後看到的表示。這通常不是您想要的，原因有兩個。它傾向於搞砸非 ASCII 字元（最明顯的是人名），以及空格（在補丁中是致命的）。執行“C-u g”以原始形式顯示訊息，然後再使用“|”來執行管道，可以解決這個問題。