Documentation/translations/zh_TW/process/submitting-patches.rst

   1 .. SPDX-License-Identifier: GPL-2.0-or-later
   2
   3 .. include:: ../disclaimer-zh_TW.rst
   4
   5 .. _tw_submittingpatches:
   6
   7 :Original: Documentation/process/submitting-patches.rst
   8
   9 :譯者:
  10  - 鍾宇 TripleX Chung <xxx.phy@gmail.com>
  11  - 時奎亮 Alex Shi <alexs@kernel.org>
  12  - 吳想成 Wu XiangCheng <bobwxc@email.cn>
  13
  14 :校譯:
  15  - 李陽 Li Yang <leoyang.li@nxp.com>
  16  - 王聰 Wang Cong <xiyou.wangcong@gmail.com>
  17  - 胡皓文 Hu Haowen <2023002089@link.tyut.edu.cn>
  18
  19
  20 提交補丁：如何讓你的改動進入內核
  21 ================================
  22
  23 對於想要將改動提交到 Linux 內核的個人或者公司來說，如果不熟悉“規矩”，
  24 提交的流程會讓人畏懼。本文檔包含了一系列建議，可以大大提高你
  25 的改動被接受的機會.
  26
  27 本文檔以較爲簡潔的行文給出了大量建議。關於內核開發流程如何進行的詳細信息，
  28 參見： Documentation/translations/zh_CN/process/development-process.rst 。
  29 Documentation/translations/zh_CN/process/submit-checklist.rst 給出了一系列
  30 提交補丁之前要檢查的事項。設備樹相關的補丁，請參閱
  31 Documentation/devicetree/bindings/submitting-patches.rst 。
  32
  33 本文檔假設您正在使用 ``git`` 準備你的補丁。如果您不熟悉 ``git`` ，最好學習
  34 如何使用它，這將使您作爲內核開發人員的生活變得更加輕鬆。
  35
  36 部分子系統和維護人員的樹有一些關於其工作流程和要求的額外信息，請參閱
  37 Documentation/process/maintainer-handbooks.rst 。
  38
  39 獲取當前源碼樹
  40 --------------
  41
  42 如果您手頭沒有當前內核源代碼的存儲庫，請使用 ``git`` 獲取一份。您需要先獲取
  43 主線存儲庫，它可以通過以下命令拉取::
  44
  45     git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
  46
  47 但是，請注意，您可能不想直接針對主線樹進行開發。大多數子系統維護人員運
  48 行自己的樹，並希望看到針對這些樹準備的補丁。請參見MAINTAINERS文件中子系
  49 統的 **T:** 項以查找該樹，或者直接詢問維護者該樹是否未在其中列出。
  50
  51 .. _tw_describe_changes:
  52
  53 描述你的改動
  54 ------------
  55
  56 描述你的問題。無論您的補丁是一行錯誤修復還是5000行新功能，都必須有一個潛在
  57 的問題激勵您完成這項工作。說服審閱者相信有一個問題值得解決，讓他們讀完第一段
  58 後就能明白這一點。
  59
  60 描述用戶可見的影響。直接崩潰和鎖定是相當有說服力的，但並不是所有的錯誤都那麼
  61 明目張膽。即使在代碼審閱期間發現了這個問題，也要描述一下您認爲它可能對用戶產
  62 生的影響。請記住，大多數Linux安裝運行的內核來自二級穩定樹或特定於供應商/產品
  63 的樹，只從上游精選特定的補丁，因此請包含任何可以幫助您將更改定位到下游的內容：
  64 觸發的場景、DMESG的摘錄、崩潰描述、性能迴歸、延遲尖峯、鎖定等。
  65
  66 質量優化和權衡。如果您聲稱在性能、內存消耗、堆棧佔用空間或二進制大小方面有所
  67 改進，請包括支持它們的數據。但也要描述不明顯的成本。優化通常不是零成本的，而是
  68 在CPU、內存和可讀性之間進行權衡；或者，做探索性的工作，在不同的工作負載之間進
  69 行權衡。請描述優化的預期缺點，以便審閱者可以權衡成本和收益。
  70
  71 提出問題之後，就要詳細地描述一下您實際在做的技術細節。對於審閱者來說，用簡練的
  72 英語描述代碼的變化是很重要的，以驗證代碼的行爲是否符合您的意圖。
  73
  74 如果您將補丁描述寫成“標準格式”，可以很容易地作爲“提交日誌”放入Linux的源代
  75 碼管理系統 ``git`` 中，那麼維護人員將非常感謝您。
  76 參見 :ref:`zh_the_canonical_patch_format` 。
  77
  78 每個補丁只解決一個問題。如果你的描述開始變長，這就表明你可能需要拆分你的補丁。
  79 請見 :ref:`zh_split_changes` 。
  80
  81 提交或重新提交補丁或補丁系列時，請包括完整的補丁說明和理由。不要
  82 只說這是補丁（系列）的第幾版。不要期望子系統維護人員引用更早的補丁版本或引用
  83 URL來查找補丁描述並將其放入補丁中。也就是說，補丁（系列）及其描述應該是獨立的。
  84 這對維護人員和審閱者都有好處。一些審閱者可能甚至沒有收到補丁的早期版本。
  85
  86 用祈使句描述你的變更，例如“make xyzzy do frotz”而不是“[This patch]make
  87 xyzzy do frotz”或“[I]changed xyzzy to do frotz”，就好像你在命令代碼庫改變
  88 它的行爲一樣。
  89
  90 如果您想要引用一個特定的提交，不要只引用提交的SHA-1 ID。還請包括提交的一行
  91 摘要，以便於審閱者瞭解它是關於什麼的。例如::
  92
  93         Commit e21d2170f36602ae2708 ("video: remove unnecessary
  94         platform_set_drvdata()") removed the unnecessary
  95         platform_set_drvdata(), but left the variable "dev" unused,
  96         delete it.
  97
  98 您還應該確保至少使用前12位SHA-1 ID。內核存儲庫包含 *許多* 對象，使較短的ID
  99 發生衝突的可能性很大。記住，即使現在不會與您的六個字符ID發生衝突，這種情況
 100 也可能在五年後改變。
 101
 102 如果該變更的相關討論或背景信息可以在網上查閱，請加上“Link:”標籤指向它。例如
 103 你的補丁修復了一個缺陷，需要添加一個帶有URL的標籤指向郵件列表存檔或缺陷跟蹤器
 104 的相關報告；如果該補丁是由一些早先郵件列表討論或網絡上的記錄引起的，請指向它。
 105
 106 當鏈接到郵件列表存檔時，請首選lore.kernel.org郵件存檔服務。用郵件中的
 107 ``Message-ID`` 頭（去掉尖括號）可以創建鏈接URL。例如::
 108
 109     Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
 110
 111 請檢查該鏈接以確保可用且指向正確的郵件。
 112
 113 不過，在沒有外部資源的情況下，也要儘量讓你的解釋可理解。除了提供郵件列表存檔或
 114 缺陷的URL之外，還要需要總結該補丁的相關討論要點。
 115
 116 如果補丁修復了特定提交中的錯誤，例如使用 ``git bisct`` 發現了一個問題，請使用
 117 帶有前12個字符SHA-1 ID的“Fixes:”標籤和單行摘要。爲了簡化解析腳本，不要將該
 118 標籤拆分爲多行，標籤不受“75列換行”規則的限制。例如::
 119
 120   Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
 121
 122 下列 ``git config`` 設置可以讓 ``git log``, ``git show`` 增加上述風格的顯示格式::
 123
 124         [core]
 125                 abbrev = 12
 126         [pretty]
 127                 fixes = Fixes: %h (\"%s\")
 128
 129 使用示例::
 130
 131         $ git log -1 --pretty=fixes 54a4f0239f2e
 132         Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
 133
 134 .. _tw_split_changes:
 135
 136 拆分你的改動
 137 ------------
 138
 139 將每個 **邏輯更改** 拆分成一個單獨的補丁。
 140
 141 例如，如果你的改動裏同時有bug修正和性能優化，那麼把這些改動拆分到兩個或
 142 者更多的補丁文件中。如果你的改動包含對API的修改，並且增加了一個使用該新API
 143 的驅動，那麼把這些修改分成兩個補丁。
 144
 145 另一方面，如果你將一個單獨的改動做成多個補丁文件，那麼將它們合併成一個
 146 單獨的補丁文件。這樣一個邏輯上單獨的改動只被包含在一個補丁文件裏。
 147
 148 需要記住的一點是，每個補丁的更改都應易於理解，以便審閱者驗證。每個補丁都應該
 149 對其價值進行闡述。
 150
 151 如果有一個補丁依賴另外一個補丁來完成它的改動，那沒問題。直接在你的補
 152 丁描述裏指出 **“這個補丁依賴某補丁”** 就好了。
 153
 154 在將您的更改劃分爲一系列補丁時，要特別注意確保內核在應用系列中的每個補丁之後
 155 都能正常構建和運行。使用 ``git bisect`` 來追蹤問題的開發者可能會在任何地方分
 156 割你的補丁系列；如果你在中間引入錯誤，他們不會感謝你。
 157
 158 如果你不能將補丁系列濃縮得更小，那麼每次大約發送出15個補丁，然後等待審閱
 159 和集成。
 160
 161 檢查你的更改風格
 162 ----------------
 163
 164 檢查您的補丁是否違反了基本樣式規定，詳細信息參見
 165 Documentation/translations/zh_CN/process/coding-style.rst
 166 中找到。如果不這樣做，只會浪費審閱者的時間，並且會導致你的補丁被拒絕，甚至
 167 可能沒有被閱讀。
 168
 169 一個重要的例外是在將代碼從一個文件移動到另一個文件時——在這種情況下，您不應
 170 該在移動代碼的同一個補丁中修改移動的代碼。這清楚地描述了移動代碼和您的更改
 171 的行爲。這大大有助於審閱實際差異，並允許工具更好地跟蹤代碼本身的歷史。
 172
 173 在提交之前，使用補丁樣式檢查程序檢查補丁（scripts/check patch.pl）。不過，
 174 請注意，樣式檢查程序應該被視爲一個指南，而不是作爲人類判斷的替代品。如果您
 175 的代碼看起來更好，但有違規行爲，那麼最好別管它。
 176
 177 檢查者報告三個級別：
 178
 179  - ERROR：很可能出錯的事情
 180  - WARNING：需要仔細審閱的事項
 181  - CHECK：需要思考的事情
 182
 183 您應該能夠判斷您的補丁中存在的所有違規行爲。
 184
 185 選擇補丁收件人
 186 --------------
 187
 188 您應該總是知會任何補丁相應代碼的子系統維護人員；查看
 189 維護人員文件和源代碼修訂歷史記錄，以瞭解這些維護人員是誰。腳本
 190 scripts/get_maintainer.pl在這個步驟中非常有用。如果您找不到正在工作的子系統
 191 的維護人員，那麼Andrew Morton（akpm@linux-foundation.org）將充當最後的維護
 192 人員。
 193
 194 您通常還應該選擇至少一個郵件列表來接收補丁集的副本。linux-kernel@vger.kernel.org
 195 是所有補丁的默認列表，但是這個列表的流量已經導致了許多開發人員不再看它。
 196 在MAINTAINERS文件中查找子系統特定的列表；您的補丁可能會在那裏得到更多的關注。
 197 不過，請不要發送垃圾郵件到無關的列表。
 198
 199 許多與內核相關的列表託管在vger.kernel.org上；您可以在
 200 http://vger.kernel.org/vger-lists.html 上找到它們的列表。不過，也有與內核相關
 201 的列表託管在其他地方。
 202
 203 不要一次發送超過15個補丁到vger郵件列表！！！！
 204
 205 Linus Torvalds是決定改動能否進入 Linux 內核的最終裁決者。他的郵件地址是
 206 torvalds@linux-foundation.org 。他收到的郵件很多，所以一般來說最好 **別**
 207 給他發郵件。
 208
 209 如果您有修復可利用安全漏洞的補丁，請將該補丁發送到 security@kernel.org 。對於
 210 嚴重的bug，可以考慮短期禁令以允許分銷商（有時間）向用戶發佈補丁；在這種情況下，
 211 顯然不應將補丁發送到任何公共列表。
 212 參見 Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。
 213
 214 修復已發佈內核中嚴重錯誤的補丁程序應該抄送給穩定版維護人員，方法是把以下列行
 215 放進補丁的籤準區（注意，不是電子郵件收件人）::
 216
 217   Cc: stable@vger.kernel.org
 218
 219 除了本文件之外，您還應該閱讀
 220 Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。
 221
 222 如果更改影響到用戶側內核接口，請向手冊頁維護人員（如維護人員文件中所列）發送
 223 手冊頁補丁，或至少發送更改通知，以便一些信息進入手冊頁。還應將用戶空間API
 224 更改抄送到 linux-api@vger.kernel.org 。
 225
 226
 227 不要MIME編碼，不要鏈接，不要壓縮，不要附件，只要純文本
 228 ------------------------------------------------------
 229
 230 Linus 和其他的內核開發者需要閱讀和評論你提交的改動。對於內核開發者來說
 231 ，可以“引用”你的改動很重要，使用一般的郵件工具，他們就可以在你的
 232 代碼的任何位置添加評論。
 233
 234 因爲這個原因，所有的提交的補丁都是郵件中“內嵌”的。最簡單（和推薦）的方法就
 235 是使用 ``git send-email`` 。https://git-send-email.io 有 ``git send-email``
 236 的交互式教程。
 237
 238 如果你選擇不用 ``git send-email`` ：
 239
 240 .. warning::
 241
 242   如果你使用剪切-粘貼你的補丁，小心你的編輯器的自動換行功能破壞你的補丁
 243
 244 不要將補丁作爲MIME編碼的附件，不管是否壓縮。很多流行的郵件軟件不
 245 是任何時候都將MIME編碼的附件當作純文本發送的，這會使得別人無法在你的
 246 代碼中加評論。另外，MIME編碼的附件會讓Linus多花一點時間來處理，這就
 247 降低了你的改動被接受的可能性。
 248
 249 例外：如果你的郵路損壞了補丁，那麼有人可能會要求你使用MIME重新發送補丁。
 250
 251 請參閱 Documentation/translations/zh_CN/process/email-clients.rst
 252 以獲取有關配置電子郵件客戶端以使其不受影響地發送補丁的提示。
 253
 254 回覆審閱意見
 255 ------------
 256
 257 你的補丁幾乎肯定會得到審閱者對補丁改進方法的評論（以回覆郵件的形式）。您必須
 258 對這些評論作出回應；讓補丁被忽略的一個好辦法就是忽略審閱者的意見。直接回復郵
 259 件來回應意見即可。不會導致代碼更改的意見或問題幾乎肯定會帶來註釋或變更日誌的
 260 改變，以便下一個審閱者更好地瞭解正在發生的事情。
 261
 262 一定要告訴審閱者你在做什麼改變，並感謝他們的時間。代碼審閱是一個累人且耗時的
 263 過程，審閱者有時會變得暴躁。即使在這種情況下，也要禮貌地回應並解決他們指出的
 264 問題。當發送下一版時，在封面郵件或獨立補丁里加上 ``patch changelog`` 說明與
 265 前一版本的不同之處（參見 :ref:`zh_the_canonical_patch_format` ）。
 266
 267 .. _tw_resend_reminders:
 268
 269 不要泄氣或不耐煩
 270 ----------------
 271
 272 提交更改後，請耐心等待。審閱者是大忙人，可能無法立即審閱您的補丁。
 273
 274 曾幾何時，補丁曾在沒收到評論的情況下消失在虛空中，但現在開發過程應該更加順利了。
 275 您應該在一週左右的時間內收到評論；如果沒有收到評論，請確保您已將補丁發送
 276 到正確的位置。在重新提交或聯繫審閱者之前至少等待一週——在諸如合併窗口之類的
 277 繁忙時間可能更長。
 278
 279 在等了幾個星期後，用帶RESEND的主題重發補丁也是可以的::
 280
 281    [PATCH Vx RESEND] sub/sys: Condensed patch summary
 282
 283 當你發佈補丁（系列）修改版的時候，不要加上“RESEND”——“RESEND”只適用於重
 284 新提交之前未經修改的補丁（系列）。
 285
 286 主題中包含 PATCH
 287 ----------------
 288
 289 由於到Linus和linux-kernel的電子郵件流量很高，通常會在主題行前面加上[PATCH]
 290 前綴。這使Linus和其他內核開發人員更容易將補丁與其他電子郵件討論區分開。
 291
 292 ``git send-email`` 會自動爲你加上。
 293
 294 簽署你的作品——開發者來源認證
 295 ------------------------------
 296
 297 爲了加強對誰做了何事的追蹤，尤其是對那些透過好幾層維護者才最終到達的補丁，我
 298 們在通過郵件發送的補丁上引入了“簽署（sign-off）”流程。
 299
 300 “簽署”是在補丁註釋最後的一行簡單文字，認證你編寫了它或者其他
 301 人有權力將它作爲開放源代碼的補丁傳遞。規則很簡單：如果你能認證如下信息:
 302
 303 開發者來源認證 1.1
 304 ^^^^^^^^^^^^^^^^^^
 305
 306 對於本項目的貢獻，我認證如下信息：
 307
 308        (a) 這些貢獻是完全或者部分的由我創建，我有權利以文件中指出
 309            的開放源代碼許可證提交它；或者
 310
 311        (b) 這些貢獻基於以前的工作，據我所知，這些以前的工作受恰當的開放
 312            源代碼許可證保護，而且，根據文件中指出的許可證，我有權提交修改後的貢獻，
 313            無論是完全還是部分由我創造，這些貢獻都使用同一個開放源代碼許可證
 314            （除非我被允許用其它的許可證）；或者
 315
 316        (c) 這些貢獻由認證（a），（b）或者（c）的人直接提供給我，而
 317            且我沒有修改它。
 318
 319        (d) 我理解並同意這個項目和貢獻是公開的，貢獻的記錄（包括我
 320            一起提交的個人記錄，包括sign-off）被永久維護並且可以和這個項目
 321            或者開放源代碼的許可證同步地再發行。
 322
 323 那麼加入這樣一行::
 324
 325   Signed-off-by: Random J Developer <random@developer.example.org>
 326
 327 使用你的真名（抱歉，不能使用假名或者匿名。）如果使用 ``git commit -s`` 的話
 328 將會自動完成。撤銷也應當包含“Signed-off-by”， ``git revert -s`` 會幫你搞定。
 329
 330 有些人會在最後加上額外的標籤。現在這些東西會被忽略，但是你可以這樣做，來標記
 331 公司內部的過程，或者只是指出關於簽署的一些特殊細節。
 332
 333 作者簽署之後的任何其他簽署（Signed-off-by:'s）均來自處理和傳遞補丁的人員，但
 334 未參與其開發。簽署鏈應當反映補丁傳播到維護者並最終傳播到Linus所經過的 **真實**
 335 路徑，首個簽署指明單個作者的主要作者身份。
 336
 337 何時使用Acked-by:，Cc:，和Co-developed-by:
 338 ------------------------------------------
 339
 340 Signed-off-by: 標籤表示簽名者參與了補丁的開發，或者他/她在補丁的傳遞路徑中。
 341
 342 如果一個人沒有直接參與補丁的準備或處理，但希望表示並記錄他們對補丁的批准/贊成，
 343 那麼他們可以要求在補丁的變更日誌中添加一個Acked-by:。
 344
 345 Acked-by: 通常由受影響代碼的維護者使用，當該維護者既沒有貢獻也沒有轉發補丁時。
 346
 347 Acked-by: 不像簽署那樣正式。這是一個記錄，確認人至少審閱了補丁，並表示接受。
 348 因此，補丁合併有時會手動將Acker的“Yep，looks good to me”轉換爲 Acked-By:（但
 349 請注意，通常最好要求一個明確的Ack）。
 350
 351 Acked-by：不一定表示對整個補丁的確認。例如，如果一個補丁影響多個子系統，並且
 352 有一個來自某個子系統維護者的Acked-By:，那麼這通常表示只確認影響維護者代碼的部
 353 分。這裏應該仔細判斷。如有疑問，應參考郵件列表存檔中的原始討論。
 354
 355 如果某人本應有機會對補丁進行評論，但沒有提供此類評論，您可以選擇在補丁中添加
 356 ``Cc:`` 這是唯一可以在沒有被該人明確同意的情況下添加的標籤——但它應該表明
 357 這個人是在補丁上抄送的。此標籤記錄了討論中包含的潛在利益相關方。
 358
 359 Co-developed-by: 聲明補丁是由多個開發人員共同創建的；當幾個人在一個補丁上工
 360 作時，它用於給出共同作者（除了From:所給出的作者之外）。因爲Co-developed-by:
 361 表示作者身份，所以每個Co-developed-by:必須緊跟在相關合作作者的簽署之後。標準
 362 簽署程序要求Signed-off-by:標籤的順序應儘可能反映補丁的時間歷史，無論作者是通
 363 過From:還是Co-developed-by:表明。值得注意的是，最後一個Signed-off-by:必須是
 364 提交補丁的開發人員。
 365
 366 注意，如果From:作者也是電子郵件標題的From:行中列出的人，則From:標籤是可選的。
 367
 368 被From:作者提交的補丁示例::
 369
 370         <changelog>
 371
 372         Co-developed-by: First Co-Author <first@coauthor.example.org>
 373         Signed-off-by: First Co-Author <first@coauthor.example.org>
 374         Co-developed-by: Second Co-Author <second@coauthor.example.org>
 375         Signed-off-by: Second Co-Author <second@coauthor.example.org>
 376         Signed-off-by: From Author <from@author.example.org>
 377
 378 被合作開發者提交的補丁示例::
 379
 380         From: From Author <from@author.example.org>
 381
 382         <changelog>
 383
 384         Co-developed-by: Random Co-Author <random@coauthor.example.org>
 385         Signed-off-by: Random Co-Author <random@coauthor.example.org>
 386         Signed-off-by: From Author <from@author.example.org>
 387         Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
 388         Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
 389
 390
 391 使用Reported-by:、Tested-by:、Reviewed-by:、Suggested-by:和Fixes:
 392 -----------------------------------------------------------------
 393
 394 Reported-by: 給那些發現錯誤並報告錯誤的人致謝，它希望激勵他們在將來再次幫助
 395 我們。請注意，如果bug是以私有方式報告的，那麼在使用Reported-by標籤之前，請
 396 先請求許可。此標籤是爲Bug設計的；請不要將其用於感謝功能請求。
 397
 398 Tested-by: 標籤表示補丁已由指定的人（在某些環境中）成功測試。這個標籤通知
 399 維護人員已經執行了一些測試，爲將來的補丁提供了一種定位測試人員的方法，並彰顯測試人員的功勞。
 400
 401 Reviewed-by：根據審閱者的監督聲明，表明該補丁已被審閱並被認爲是可接受的：
 402
 403
 404 審閱者的監督聲明
 405 ^^^^^^^^^^^^^^^^
 406
 407 通過提供我的Reviewed-by:標籤，我聲明：
 408
 409         (a) 我已經對這個補丁進行了一次技術審閱，以評估它是否適合被包含到
 410             主線內核中。
 411
 412         (b) 與補丁相關的任何問題、顧慮或問題都已反饋給提交者。我對提交者對
 413             我的評論的回應感到滿意。
 414
 415         (c) 雖然這一提交可能仍可被改進，但我相信，此時，（1）對內核
 416             進行了有價值的修改，（2）沒有包含爭論中涉及的已知問題。
 417
 418         (d) 雖然我已經審閱了補丁並認爲它是健全的，但我不會（除非另有明確
 419             說明）作出任何保證或擔保它會在任何給定情況下實現其規定的目的
 420             或正常運行。
 421
 422 Reviewed-by是一種觀點聲明，即補丁是對內核的適當修改，沒有任何遺留的嚴重技術
 423 問題。任何感興趣的審閱者（完成工作的人）都可以爲一個補丁提供一個Reviewed-by
 424 標籤。此標籤用於向審閱者提供致謝，並通知維護者補丁的審閱進度。
 425 當Reviewed-by:標籤由已知了解主題區域並執行徹底檢查的審閱者提供時，通常會增加
 426 補丁進入內核的可能性。
 427
 428 一旦從測試人員或審閱者的“Tested-by”和“Reviewed-by”標籤出現在郵件列表中，
 429 作者應在發送下一個版本時將其添加到適用的補丁中。但是，如果補丁在以下版本中發
 430 生了實質性更改，這些標籤可能不再適用，因此應該刪除。通常，在補丁更改日誌中
 431 （在 ``---`` 分隔符之後）應該提到刪除某人的測試者或審閱者標籤。
 432
 433 Suggested-by: 表示補丁的想法是由指定的人提出的，並確保將此想法歸功於指定的
 434 人。請注意，未經許可，不得添加此標籤，特別是如果該想法未在公共論壇上發佈。
 435 也就是說，如果我們勤快地致謝創意提供者，他們將受到鼓舞，很有希望在未來再次
 436 幫助我們。
 437
 438 Fixes: 指示補丁修復了之前提交的一個問題。它可以便於確定錯誤的來源，這有助於
 439 檢查錯誤修復。這個標籤還幫助穩定內核團隊確定應該接收修復的穩定內核版本。這是
 440 指示補丁修復的錯誤的首選方法。請參閱 :ref:`zh_describe_changes` 瞭解更多信息。
 441
 442 .. note::
 443
 444   附加Fixes:標籤不會改變穩定內核規則流程，也不改變所有穩定版補丁抄送
 445   stable@vger.kernel.org的要求。有關更多信息，請閱讀
 446   Documentation/translations/zh_CN/process/stable-kernel-rules.rst 。
 447
 448 .. _tw_the_canonical_patch_format:
 449
 450 標準補丁格式
 451 ------------
 452
 453 本節描述如何格式化補丁本身。請注意，如果您的補丁存儲在 ``Git`` 存儲庫中，則
 454 可以使用 ``git format-patch`` 進行正確的補丁格式化。但是，這些工具無法創建
 455 必要的文本，因此請務必閱讀下面的說明。
 456
 457 標準的補丁標題行是::
 458
 459     Subject: [PATCH 001/123] 子系統:一句話概述
 460
 461 標準補丁的信體包含如下部分：
 462
 463   - 一個 ``from`` 行指出補丁作者。後跟空行（僅當發送補丁的人不是作者時才需要）。
 464
 465   - 說明文字，每行最長75列，這將被複制到永久變更日誌來描述這個補丁。
 466
 467   - 一個空行
 468
 469   - 上述的 ``Signed-off-by:`` 行，也將出現在更改日誌中。
 470
 471   - 只包含 ``---`` 的標記線。
 472
 473   - 任何其他不適合放在變更日誌的註釋。
 474
 475   - 實際補丁（ ``diff`` 輸出）。
 476
 477 標題行的格式，使得對標題行按字母序排序非常的容易——很多郵件客戶端都
 478 可以支持——因爲序列號是用零填充的，所以按數字排序和按字母排序是一樣的。
 479
 480 郵件標題中的“子系統”標識哪個內核子系統將被打補丁。
 481
 482 郵件標題中的“一句話概述”扼要的描述郵件中的補丁。“一句話概述”
 483 不應該是一個文件名。對於一個補丁系列（“補丁系列”指一系列的多個相關補
 484 丁），不要對每個補丁都使用同樣的“一句話概述”。
 485
 486 記住郵件的“一句話概述”會成爲該補丁的全局唯一標識。它會進入 ``git``
 487 的改動記錄裏。然後“一句話概述”會被用在開發者的討論裏，用來指代這個補
 488 丁。用戶將希望通過搜索引擎搜索“一句話概述”來找到那些討論這個補丁的文
 489 章。當人們在兩三個月後使用諸如 ``gitk`` 或 ``git log --oneline`` 之類
 490 的工具查看數千個補丁時，也會很快看到它。
 491
 492 出於這些原因，概述必須不超過70-75個字符，並且必須描述補丁的更改以及爲
 493 什麼需要補丁。既要簡潔又要描述性很有挑戰性，但寫得好的概述應該這樣。
 494
 495 概述的前綴可以用方括號括起來：“Subject: [PATCH <tag>...] <概述>”。標記
 496 不被視爲概述的一部分，而是描述應該如何處理補丁。如果補丁的多個版本已發
 497 送出來以響應評審（即“v1，v2，v3”）則必須包含版本號，或包含“RFC”以指示
 498 評審請求。如果一個補丁系列中有四個補丁，那麼各個補丁可以這樣編號：1/4、2/4、
 499 3/4、4/4。這可以確保開發人員瞭解補丁應用的順序，且
 500 已經查看或應用了補丁系列中的所有補丁。
 501
 502 一些標題的例子::
 503
 504     Subject: [patch 2/5] ext2: improve scalability of bitmap searching
 505     Subject: [PATCHv2 001/207] x86: fix eflags tracking
 506
 507 ``From`` 行是信體裏的最上面一行，具有如下格式::
 508
 509         From: Patch Author <author@example.com>
 510
 511 ``From`` 行指明在永久改動日誌裏，誰會被確認爲作者。如果沒有 ``From`` 行，那
 512 麼郵件頭裏的 ``From:`` 行會被用來決定改動日誌中的作者。
 513
 514 說明文字將會被提交到永久的源代碼改動日誌裏，因此應針對那些早已經不記得和這
 515 個補丁相關的討論細節的讀者。包括補丁處理的故障症狀（內核日誌消息、oops消息
 516 等），這對於可能正在搜索提交日誌以查找適用補丁的人特別有用。文本應該寫得如
 517 此詳細，以便在數週、數月甚至數年後閱讀時，能夠爲讀者提供所需的細節信息，以
 518 掌握創建補丁的 **原因** 。
 519
 520 如果一個補丁修復了一個編譯失敗，那麼可能不需要包含 *所有* 編譯失敗；
 521 只要足夠讓搜索補丁的人能夠找到它就行了。與概述一樣，既要簡潔又要描述性。
 522
 523 ``---`` 標記行對於補丁處理工具要找到哪裏是改動日誌信息的結束，是不可缺少
 524 的。
 525
 526 對於 ``---`` 標記之後的額外註解，一個好的用途就是用來寫 ``diffstat`` ，用來顯
 527 示修改了什麼文件和每個文件都增加和刪除了多少行。 ``diffstat`` 對於比較大的補
 528 丁特別有用。
 529 使用 ``diffstat`` 的選項 ``-p 1 -w 70`` 這樣文件名就會從內核源代碼樹的目錄開始
 530 ，不會佔用太寬的空間（很容易適合80列的寬度，也許會有一些縮進。）
 531 （ ``git`` 默認會生成合適的diffstat。）
 532
 533 其餘那些只適用於當時或者與維護者相關的註解，不合適放到永久的改動日誌裏的，也
 534 應該放這裏。較好的例子就是 ``補丁更改記錄`` ，記錄了v1和v2版本補丁之間的差異。
 535
 536 請將此信息放在將變更日誌與補丁的其餘部分分隔開的 ``---`` 行 **之後** 。版本
 537 信息不是提交到git樹的變更日誌的一部分。只是供審閱人員使用的附加信息。如果將
 538 其放置在提交標記上方，則需要手動交互才能將其刪除。如果它位於分隔線以下，則在
 539 應用補丁時會自動剝離::
 540
 541   <commit message>
 542   ...
 543   Signed-off-by: Author <author@mail>
 544   ---
 545   V2 -> V3: Removed redundant helper function
 546   V1 -> V2: Cleaned up coding style and addressed review comments
 547
 548   path/to/file | 5+++--
 549   ...
 550
 551 在後面的參考資料中能看到正確補丁格式的更多細節。
 552
 553 .. _tw_backtraces:
 554
 555 提交消息中的回溯（Backtraces）
 556 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 557
 558 回溯有助於記錄導致問題的調用鏈。然而，並非所有回溯都有幫助。例如，早期引導調
 559 用鏈是獨特而明顯的。而逐字複製完整的dmesg輸出則會增加時間戳、模塊列表、寄存
 560 器和堆棧轉儲等分散注意力的信息。
 561
 562 因此，最有用的回溯應該從轉儲中提取相關信息，以更容易集中在真實問題上。下面是
 563 一個剪裁良好的回溯示例::
 564
 565   unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)
 566   at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
 567   Call Trace:
 568   mba_wrmsr
 569   update_domains
 570   rdtgroup_mkdir
 571
 572 .. _tw_explicit_in_reply_to:
 573
 574 明確回覆郵件頭（In-Reply-To）
 575 -----------------------------
 576
 577 手動添加回復補丁的的郵件頭（In-Reply_To:）是有用的（例如，使用 ``git send-email`` ），
 578 可以將補丁與以前的相關討論關聯起來，例如，將bug補丁鏈接到電子郵件和bug報告。
 579 但是，對於多補丁系列，最好避免在回覆時使用鏈接到該系列的舊版本。這樣，
 580 補丁的多個版本就不會成爲電子郵件客戶端中無法管理的引用樹。如果鏈接有用，
 581 可以使用 https://lore.kernel.org/ 重定向器（例如，在封面電子郵件文本中）
 582 鏈接到補丁系列的早期版本。
 583
 584 給出基礎樹信息
 585 --------------
 586
 587 當其他開發人員收到您的補丁並開始審閱時，知道應該將您的工作放到代碼樹歷史記錄
 588 中的什麼位置通常很有用。這對於自動化持續集成流水（CI）特別有用，這些流水線試
 589 圖運行一系列測試，以便在維護人員開始審閱之前確定提交的質量。
 590
 591 如果您使用 ``git format-patch`` 生成補丁，則可以通過 ``--base`` 標誌在提交中
 592 自動包含基礎樹信息。使用此選項最簡單、最方便的方法是配合主題分支::
 593
 594     $ git checkout -t -b my-topical-branch master
 595     Branch 'my-topical-branch' set up to track local branch 'master'.
 596     Switched to a new branch 'my-topical-branch'
 597
 598     [perform your edits and commits]
 599
 600     $ git format-patch --base=auto --cover-letter -o outgoing/ master
 601     outgoing/0000-cover-letter.patch
 602     outgoing/0001-First-Commit.patch
 603     outgoing/...
 604
 605 當你編輯 ``outgoing/0000-cover-letter.patch`` 時，您會注意到在它的最底部有一
 606 行 ``base-commit:`` 尾註，它爲審閱者和CI工具提供了足夠的信息以正確執行
 607 ``git am`` 而不必擔心衝突::
 608
 609     $ git checkout -b patch-review [base-commit-id]
 610     Switched to a new branch 'patch-review'
 611     $ git am patches.mbox
 612     Applying: First Commit
 613     Applying: ...
 614
 615 有關此選項的更多信息，請參閱 ``man git-format-patch`` 。
 616
 617 .. note::
 618
 619     ``--base`` 功能是在2.9.0版git中引入的。
 620
 621 如果您不使用git格式化補丁，仍然可以包含相同的 ``base-commit`` 尾註，以指示您
 622 的工作所基於的樹的提交哈希。你應該在封面郵件或系列的第一個補丁中添加它，它應
 623 該放在 ``---`` 行的下面或所有其他內容之後，即只在你的電子郵件簽名之前。
 624
 625 參考文獻
 626 --------
 627
 628 Andrew Morton，“完美的補丁”（tpp）
 629   <https://www.ozlabs.org/~akpm/stuff/tpp.txt>
 630
 631 Jeff Garzik，“Linux內核補丁提交格式”
 632   <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html>
 633
 634 Greg Kroah-Hartman，“如何惹惱內核子系統維護人員”
 635   <http://www.kroah.com/log/linux/maintainer.html>
 636
 637   <http://www.kroah.com/log/linux/maintainer-02.html>
 638
 639   <http://www.kroah.com/log/linux/maintainer-03.html>
 640
 641   <http://www.kroah.com/log/linux/maintainer-04.html>
 642
 643   <http://www.kroah.com/log/linux/maintainer-05.html>
 644
 645   <http://www.kroah.com/log/linux/maintainer-06.html>
 646
 647 不！！！別再發巨型補丁炸彈給linux-kernel@vger.kernel.org的人們了！
 648   <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
 649
 650 內核 Documentation/translations/zh_CN/process/coding-style.rst
 651
 652 Linus Torvalds關於標準補丁格式的郵件
 653   <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org>
 654
 655 Andi Kleen，“提交補丁之路”
 656   一些幫助合入困難或有爭議的變更的策略。
 657
 658   http://halobates.de/on-submitting-patches.pdf
 659