linux 核心開發指南 - 5 傳送補丁

摘要： 5. 傳送補丁 遲早，當您的工作準備好提交給社群進行審查，並最終包含到主線核心中時。不出所料， 核心開發社群已經發展出一套用於釋出補丁的約定和過程；遵循這些約定和過程將使 參與其中的每個人的生活更加輕鬆。本檔案將試圖合理詳細地涵蓋這些期望；更多資訊 也可在以下檔案中找到 Documenta...

5. 傳送補丁

遲早，當您的工作準備好提交給社群進行審查，並最終包含到主線核心中時。不出所料， 核心開發社群已經發展出一套用於釋出補丁的約定和過程；遵循這些約定和過程將使 參與其中的每個人的生活更加輕鬆。本檔案將試圖合理詳細地涵蓋這些期望；更多資訊 也可在以下檔案中找到 Documentation/translations/zh_CN/process/submitting-patches.rst, Documentation/process/submitting-drivers.rst 和 Documentation/translations/zh_CN/process/submit-checklist.rst.

5.1. 何時郵寄

在補丁完全“準備好”之前，有一個不斷的誘惑來避免釋出補丁。對於簡單的補丁， 這不是問題。但是，如果正在完成的工作很複雜，那麼在工作完成之前從社群獲得 反饋就可以獲得很多好處。因此，您應該考慮釋出正在進行的工作，甚至使Git樹 可用，以便感興趣的開發人員可以隨時趕上您的工作。

當釋出還沒有準備好包含的程式碼時，最好在釋出本身中這樣說。還應提及任何有待完成 的主要工作和任何已知問題。很少有人會看到那些被認為是半生不熟的補丁，但是那些 人會想到他們可以幫助你把工作推向正確的方向。

5.2. 建立補丁之前

在考慮將補丁傳送到開發社群之前，有許多事情應該做。這些包括：

• 儘可能地測試程式碼。利用核心的除錯工具，確保核心使用所有合理的配置選項組合 進行構建，使用跨編譯器為不同的體系結構進行構建等。

• 確保您的程式碼符合核心編碼風格指南。

• 您的更改是否具有效能影響？如果是這樣，您應該執行基準測試來顯示您的變更的 影響（或好處）；結果的摘要應該包含在補丁中。

• 確保您有權釋出程式碼。如果這項工作是為僱主完成的，僱主對這項工作具有所有權， 並且必須同意根據GPL對其進行放行。

一般來說，在釋出程式碼之前進行一些額外的思考，幾乎總是能在短時間內得到回報。

5.3. 補丁準備

準備釋出補丁可能是一個驚人的工作量，但再次嘗試節省時間在這裡通常是不明智的， 即使在短期內。

必須針對核心的特定版本準備補丁。作為一般規則，補丁程式應該基於Linus的Git樹中 的當前主線。當以主線為基礎時，從一個眾所周知的釋出點開始——一個穩定的或RC的 釋出——而不是在一個主線分支任意點。

但是，可能需要針對-mm、linux-next或子系統樹生成版本，以便於更廣泛的測試和審查。 根據補丁的區域以及其他地方的情況，針對這些其他樹建立補丁可能需要大量的工作來 解決衝突和處理API更改。

只有最簡單的更改才應格式化為單個補丁；其他所有更改都應作為一系列邏輯更改進行。 分割補丁是一門藝術；一些開發人員花了很長時間來弄清楚如何按照社群期望的方式來 做。然而，有一些經驗法則可以大大幫助：

• 您釋出的補丁程式系列幾乎肯定不會是工作系統中的一系列更改。相反，您所做的 更改需要在最終形式中加以考慮，然後以有意義的方式進行拆分。開發人員對離散的、 自包含的更改感興趣，而不是您獲取這些更改的路徑。

• 每個邏輯上獨立的變更都應該格式化為單獨的補丁。這些更改可以是小的（“向此 結構新增欄位”）或大的（例如，新增一個重要的新驅動程式），但它們在概念上 應該是小的，並且可以接受一行描述。每個補丁都應該做一個特定的更改，可以單獨 檢查並驗證它所做的事情。

• 作為重申上述準則的一種方法：不要在同一補丁中混合不同型別的更改。如果一個 補丁修復了一個關鍵的安全漏洞，重新排列了一些結構，並重新格式化了程式碼，那麼 很有可能它會被忽略，而重要的修復將丟失。

• 每個補丁都應該產生一個核心，它可以正確地構建和執行；如果補丁系列在中間被 中斷，那麼結果應該仍然是一個工作的核心。補丁系列的部分應用是使用 “git bisct”工具查找回歸的一個常見場景；如果結果是一個損壞的核心，那麼對於 那些從事追蹤問題的高尚工作的開發人員和使用者來說，將使他們的生活更加艱難。

• 不過，不要過分。一位開發人員曾經將一組編輯內容作為500個單獨的補丁釋出到一個 檔案中，這並沒有使他成為核心郵件列表中最受歡迎的人。一個補丁可以相當大， 只要它仍然包含一個單一的邏輯變更。

• 用一系列補丁新增一個全新的基礎設施是很有誘惑力的，但是在系列中的最後一個 補丁啟用整個補丁之前，該基礎設施是不使用的。如果可能的話，應該避免這種 誘惑；如果這個系列增加了迴歸，那麼二分法將指出最後一個補丁是導致問題的 補丁，即使真正的bug在其他地方。只要有可能，新增新程式碼的補丁程式應該立即 啟用該程式碼。

建立完美補丁系列的工作可能是一個令人沮喪的過程，在完成“真正的工作”之後需要花費 大量的時間和思考。但是，如果做得好，這是一段很好的時間。

5.4. 補丁格式和更改日誌

所以現在你有了一系列完美的補丁可以釋出，但是這項工作還沒有完成。每個補丁都 需要被格式化成一條訊息，它可以快速而清晰地將其目的傳達給世界其他地方。為此， 每個補丁將由以下部分組成：

• 命名補丁作者的可選“from”行。只有當你通過電子郵件傳遞別人的補丁時，這一行 才是必要的，但是如果有疑問，新增它不會有任何傷害。

• 一行描述補丁的作用。對於沒有其他上下文的讀者來說，此訊息應該足夠了解補丁 的範圍；這是將在“短格式”變更日誌中顯示的行。此訊息通常首先用相關的子系統 名稱格式化，然後是補丁的目的。例如：

  gpio: fix build on CONFIG_GPIO_SYSFS=n
  

• 一個空白行，後面是補丁內容的詳細描述。這個描述可以是必需的；它應該說明補丁 的作用以及為什麼它應該應用於核心。

• 一個或多個標記行，至少有一個由補丁作者的：signed-off-by 簽名。簽名將在下面 更詳細地描述。

上面的專案一起構成補丁的變更日誌。寫一篇好的變更日誌是一門至關重要但常常被 忽視的藝術；值得花一點時間來討論這個問題。當你寫一個變更日誌時，你應該記住 有很多不同的人會讀你的話。其中包括子系統維護人員和審查人員，他們需要決定是否 應該包括補丁，分銷商和其他維護人員試圖決定是否應該將補丁反向移植到其他核心， bug搜尋人員想知道補丁是否負責他們正在追查的問題，想知道核心如何變化的使用者。 等等。一個好的變更日誌以最直接和最簡潔的方式向所有這些人傳達所需的資訊。

為此，總結行應該描述變更的影響和動機，以及在一行約束條件下可能發生的變化。 然後，詳細的描述可以詳述這些主題，並提供任何需要的附加資訊。如果補丁修復了 一個bug，請引用引入該bug的commit（如果可能，請在引用commits時同時提供commit id 和標題）。如果某個問題與特定的日誌或編譯器輸出相關聯，請包含該輸出以幫助其他 人搜尋同一問題的解決方案。如果更改是為了支援以後補丁中的其他更改，那麼就這麼 說。如果更改了內部API，請詳細說明這些更改以及其他開發人員應該如何響應。一般 來說，你越能把自己放在每個閱讀你的changelog的人的位置上，changelog（和核心 作為一個整體）就越好。

不用說，變更日誌應該是將變更提交到修訂控制系統時使用的文字。接下來是：

• 補丁本身，採用統一的（“-u”）補丁格式。將“-p”選項用於diff將使函式名與更改 相關聯，從而使結果補丁更容易被其他人讀取。

您應該避免在補丁中包括對不相關檔案（例如，由構建過程生成的檔案或編輯器 備份檔案）的更改。文件目錄中的檔案“dontdiff”在這方面有幫助；使用“-X”選項將 其傳遞給diff。

上面提到的標籤用於描述各種開發人員如何與這個補丁的開發相關聯。 Documentation/translations/zh_CN/process/submitting-patches.rst 文件中對它們進行了詳細描述；下面是一個簡短的總結。每一行的格式如下：

tag: Full Name <email address>optional-other-stuff

常用的標籤有：

• Signed-off-by: 這是一個開發人員的證明，他或她有權提交補丁以包含到核心中。 這是開發來源認證協議，其全文可在 Documentation/translations/zh_CN/process/submitting-patches.rst 中找到，如果沒有適當的簽字，則不能合併到主線中。

• Co-developed-by: 宣告補丁是由多個開發人員共同建立的；當幾個人在一個補丁上 工作時，它用於將屬性賦予共同作者（除了 From: 所賦予的作者之外）。因為 Co-developed-by: 表示作者身份，所以每個共同開發人, 必須緊跟在相關合作作者 的簽名之後。具體內容和示例可以在以下檔案中找到 Documentation/translations/zh_CN/process/submitting-patches.rst

• Acked-by: 表示另一個開發人員（通常是相關程式碼的維護人員）同意補丁適合包含 在核心中。

• Tested-by: 宣告指定的人已經測試了補丁並發現它可以工作。

• Reviewed-by: 指定的開發人員已經審查了補丁的正確性；有關詳細資訊，請參閱 Documentation/translations/zh_CN/process/submitting-patches.rst

• Reported-by: 指定報告此補丁修復的問題的使用者；此標記用於提供感謝。

• Cc：指定的人收到了補丁的副本，並有機會對此發表評論。

在補丁中新增標籤時要小心：只有cc:才適合在沒有指定人員明確許可的情況下新增。

5.5. 傳送補丁

在郵寄補丁之前，您還需要注意以下幾點：

• 您確定您的郵件傳送程式不會損壞補丁嗎？有免費的空白更改或由郵件客戶端 執行的行包裝的補丁不會在另一端復原，並且通常不會進行任何詳細檢查。如果有 任何疑問，把補丁寄給你自己，讓你自己相信它是完好無損的。

  Documentation/translations/zh_CN/process/email-clients.rst 提供了一些有用的提示，可以讓特定的郵件客戶機工作以傳送補丁。

• 你確定你的補丁沒有愚蠢的錯誤嗎？您應該始終通過scripts/checkpatch.pl執行 補丁程式，並解決它提出的投訴。請記住，checkpatch.pl雖然是大量思考核心 補丁應該是什麼樣子的體現，但它並不比您聰明。如果修復checkpatch.pl投訴會 使程式碼變得更糟，請不要這樣做。

補丁應始終以純文字形式傳送。請不要將它們作為附件傳送；這使得審閱者在答覆中更難 引用補丁的部分。相反，只需將補丁直接放到您的訊息中。

郵寄補丁時，重要的是將副本傳送給任何可能感興趣的人。與其他一些專案不同，核心 鼓勵人們錯誤地傳送過多的副本；不要假定相關人員會看到您在郵件列表中的釋出。 尤其是，副本應傳送至：

• 受影響子系統的維護人員。如前所述，維護人員檔案是查詢這些人員的第一個地方。

• 其他在同一領域工作的開發人員，尤其是那些現在可能在那裡工作的開發人員。使用 git檢視還有誰修改了您正在處理的檔案，這很有幫助。

• 如果您對錯誤報告或功能請求做出響應，也可以抄送原始傳送人。

• 將副本傳送到相關郵件列表，或者，如果沒有其他應用，則傳送到Linux核心列表。

• 如果您正在修復一個bug，請考慮該修復是否應進入下一個穩定更新。如果是這樣， stable@ vger. kernel. org 應該得到補丁的副本。另外，在補丁本身的標籤中新增 一個“cc:[email protected]”；這將使穩定團隊在修復進入主線時收到通知。

當為一個補丁選擇接收者時，最好知道你認為誰最終會接受這個補丁並將其合併。雖然 可以將補丁直接傳送給LinusTorvalds並讓他合併，但通常情況下不會這樣做。Linus 很忙，並且有子系統維護人員負責監視核心的特定部分。通常您會希望維護人員合併您 的補丁。如果沒有明顯的維護人員，Andrew Morton通常是最後的補丁目標。

補丁需要好的主題行。補丁程式行的規範格式如下：

[PATCH nn/mm] subsys: one-line description of the patch

其中“nn”是補丁的序號，“mm”是系列中補丁的總數，“subsys”是受影響子系統的名稱。 顯然，一個單獨的補丁可以省略nn/mm。

如果您有一系列重要的補丁，那麼通常將介紹性描述作為零部分發送。不過，這種約定 並沒有得到普遍遵循；如果您使用它，請記住簡介中的資訊不會使它進入核心變更日誌。 因此，請確保補丁本身具有完整的變更日誌資訊。

一般來說，多部分補丁的第二部分和後續部分應作為對第一部分的回覆傳送，以便它們 在接收端都連線在一起。像git和coilt這樣的工具有命令，可以通過適當的執行緒傳送 一組補丁。但是，如果您有一個長系列，並且正在使用git，請遠離–chain reply-to 選項，以避免建立異常深的巢狀。

關於我們：

阿里巴巴作業系統研發團隊負責阿里經濟體的伺服器作業系統,以及Linux核心的研發與產品化。團隊針對阿里巴巴各業務的需求，新技術的發展，新硬體的引入，在核心與作業系統等基礎領域 進行研究創新。目前已經形成 Ali OS, Ali Cloud Linux, Daishu雲原生作業系統等多個產品。

加入我們，你可以跟傳說中的多隆大神一起工作，你可以不斷挑戰基礎軟體領域的新技術，你可以向社群提 Patch，你的工作可以應用到阿里巴巴的數 十萬臺伺服器上。阿里巴巴作業系統研發團隊，期待你的加入, 簡歷傳送: [email protected]