# 發第一份 patch 到 Linux kernel
研讀老師的教材 LKMPG 時，對於 sysfs、 kobject 的存在特別疑惑，我因此去研讀 Linux kernel /samples/kobject/kobject-example.c 的範例程式碼，因緣際會發現 kobject-example.c 和 kset-example.c 有一些註解錯誤，還有一個應該定義為 const 的結構體沒定義成 const。就想到可以藉此機會練習發送 Linux kernel patch。

在發 patch 之前參考了其他人的經驗：
* [第一次給Linux Kernel發patch](/3ZmFP8MaT2ysOpnHJi9zmA)
* [第一次發 patch 到 linux kernel (含注意事項)](/GCoQFJ-iStKJKx81B9gPxw)
* [提交第一份 Patch 到 Linux Kernel](/hB7EJRPBRXGNfpAchzXm_g) by rota1001
* [提交第一份 Patch 到 Linux Kernel](/bZ0xpeo6TqOMoOHlTiApZg) by Steve Lung

非常建議一定要看完 [Documentation/process/submitting-patches.rst](https://www.kernel.org/doc/html/latest/process/submitting-patches.html#submittingpatches)，因為如果遇到別人沒遇過的問題，這時還是得回歸到文件的說明。

上述幾份資料在流程方面寫得很完整，我這邊不再重述。

所以我便提一些自己碰到的問題、犯的錯，讓有意願貢獻的人看到能避免採坑。

---

## 流程
因為我筆電的 Linux 被我用壞了，現在要用伺服器重設環境一次，所以乾脆把過流程一遍的流程再寫一遍

### 下載 Linux 原始碼
下載最新的 release 然後解壓縮，以 v6.16-rc7 為例

$ wget https://github.com/torvalds/linux/archive/refs/tags/v6.16-rc7.tar.gz
$ tar -zxvf v6.16-rc7.tar.gz

### 初始化 git
以下命令均在 linux 原始碼目錄內操作

$ cd linux-6.16-rc7
$ git init
$ git add .
$ git commit -m "orig"
$ git branch develop
$ git checkout develop
$ git config --global user.email "[e-mail]"
$ git config --global user.name "Meng Shao Liu"

### 修改並 commit
用編輯器修改完檔案後 commit

$ git add .
$ cd ../../.. # back to root directory
$ git commit -s -v

### 生成 patch

$ git format-patch master

用腳本檢查 patch

$ ./scripts/checkpatch.pl patch檔名

### 設定 SMTP
要用 `git send-email` 必須設定 SMTP

$ vi ~/.gitconfig

若使用 gmail 發送的話，必須前往 google 帳戶設定應用程式密碼，步驟請看 [Google 官方教學](https://support.google.com/accounts/answer/185833?hl=zh-Hant)，設定完得到 16 位的密碼填入下方欄位

[sendemail]
        smtpencryption=tls
        smtpserver=smtp.gmail.com
        smtpuser=[e-mail]
        smtpserverport=587
        smtpPass=你的Google應用程式密碼

### 查看 maintainer

./scripts/get_maintainer.pl [patch]

### 寄送
先寄給自己測試

$ git send-email --to [e-mail] 0001-for-testing.patch

確認沒問題後，寄給 maintainer 並 cc 相關的開發者。

$ git send-email --to [e-mail] --cc [e-mail],[e-mail] 0001-docs-devicetree-Fix-typo-in-lvds.yaml.patch

### 後續回覆
必須使用 mutt 或 git send-email 進行 email 回覆

sudo apt install mutt // Ubuntu, Debian
sudo dnf install mutt // fedora

進行 mutt 的初始設定

$ vi ~/.muttrc

set ssl_force_tls=yes
set imap_user = "你的信箱@XXXX.com"
set imap_pass = "你的APP密碼"
set from="你的信箱@XXXX.com"
set realname="FIRST_NAME LAST_NAME"
set folder = "imaps://imap.gmail.com/"
set spoolfile = "imaps://imap.gmail.com/INBOX"
set postponed="imaps://imap.gmail.com/[Gmail]/Drafts"
set header_cache = "~/.mutt/cache/headers"
set message_cachedir = "~/.mutt/cache/bodies"
set certificate_file = "~/.mutt/certificates"
set smtp_url = "smtps://你的信箱@XXX.com:你的APP密碼@smtp.gmail.com:465/"
set record="~/mail/sent"
set move = no
set imap_keepalive = 900

以下是讓 mutt 更好用的進階設定，比如從新到舊排序，設定本地 cache 避免每次都從雲端抓取資料。

set sort = 'reverse-date'
set sort_aux = 'reverse-last-date-received'

set header_cache = "~/.mutt/cache/headers"
set message_cachedir = "~/.mutt/cache/bodies"

set mark_old = no

macro index <F2> "l~d<7d\n" "Show mail from the last month"

set imap_check_subscribed

使用 mutt 回覆方式：打開要回覆的 mail，直接按 r，進入回覆模式
回覆完成寄出後在 lkml 就能看到回覆的結構了

### 編譯 kernel
https://docs.kernel.org/process/submit-checklist.html

---
### 踩坑

#### 對應的檔案找不到 maintainer
我修改的檔案所屬的目錄 `/sample/kobject` 並沒有紀錄在名冊的 maintainer，就不知道 patch 應該寄給誰，一般來說碰到這種情況有以下解決方法：
1. 寄給 Andrew Morton
2. 看同一個目錄，以及鄰近上下層目錄等相關子系統最近的幾次維護是由誰 review，寄給那位 maintainer

而我的情況是，`/sample/kobject` 過去幾年的 patch 都由 Greg Kroah-Hartman review，所以我選擇寄給 Greg Kroah-Hartman

#### 真名格式不對
[第一版 patch](https://lore.kernel.org/all/2025071548-spectator-driller-0dae@gregkh/) 我在姓與名之間加了一個點「.」。被 Greg 提醒應該修正。
於是後續我用 `git config` 把名字裡面的橫槓和點都移除，然後把 commit message 裡面的簽名也一併修正。

#### 嚴格對待 commit message
我在[第一版 patch](https://lore.kernel.org/all/2025071506-bundle-fondling-6a94@gregkh/) 的 commit message 有一句可能誤導其他人的訊息，也被 Greg 提醒要刪除。

我認為 commit message 的問題很難靠自己察覺，但還是盡量用最嚴謹的態度審視用到的每一個字句，因為 commit message 是未來的人查詢你這次 commit 的變更時會看到的第一個說明，如果對方還要繼續追溯問題才會看到你 patch 的 additional comments。

#### LKML.ORG 無法正確顯示 patch
我的[第二個 patch](https://lkml.org/lkml/2025/7/16/113) 在 LKML.ORG 上會無法正確顯示，我本來猶豫要不要重新寄一份，但是 Greg KH 和 LKML kernel Lore 上均可以正確顯示。所以此應為 LKML.ORG 本身的 Bug。

#### 發送 patch series 時要將 patch 串連
如果一次發送一個以上的 patch 就稱為 patch series。patch series 一定要把每一個 patch 的串連。
如果舉我的例子，在[第三版的 patch](https://lore.kernel.org/all/[e-mail]/)，一次發送兩個 patch 的 patch series 時要將第二個 patch 回覆在第一個 patch 底下。
也就是第二個 patch file 的 Message-ID 必須添加 In-Reply-To: <第一個 patch 的 Message-ID>

From: Meng Shao Liu <[e-mail]>
To: [e-mail]
Cc: [e-mail], [e-mail],
	Meng Shao Liu <[e-mail]>
Subject: [PATCH v3 2/2] samples/kobject: make attribute_group const
Date: Wed, 16 Jul 2025 14:46:29 +0800	[thread overview]
Message-ID: <[e-mail]> (raw)
In-Reply-To: <[e-mail]>

可以借助 `git format-patch --thread`，自動把第二個 patch in-reply-to 第一個 patch。

另外，如果 patch 數量很多，可以使用 `git format-patch --cover-letter`，這樣加上 cover letter 大概講述整個 patch series，而後續所有的 patch 都會 in-reply-to cover letter。例子請看其他貢獻者的 [patch](https://lkml.org/lkml/2025/7/2/56)

要注意的是，如果要寄給自己測試時，用 gmail 查看自己的 patch series 可能看不到 reply 的結構，並不是串連失敗，而是 gmail 的問題，改成使用 mutt 就看的到了。

#### 修正後再發送 patch
如果 patch 需要修正要再發送，並不是 resend，resend 的情況僅適用於 patch 均未修改且 maintainer 一周以後尚未回覆，resend 會需要標示 RESEND 的 prefix，例如 `[PATCH RESEND]`。
對於 patch 修正後再發送必須標註版本號，`git format-patch -vn`，顯示此 patch 是修改後的第 n 次再發送。而再發送的 patch 不需要回覆在之前的 patch。

#### 未標註版本號
如果 patch 第一次沒有被採納的話，後續修正完標題一定要標示版本號，這裡我犯一次錯，我在[第二版 patch](https://lore.kernel.org/all/2025071648-atonable-antihero-2df2@gregkh/) 的標題沒有標註版本號，被 Greg 幫忙讀 patch 的 AI 提醒。

[PATCH 2/2] samples/kobject: make attribute_group const

|
V

[PATCH v2 2/2] samples/kobject: make attribute_group const

|
V

[PATCH v3 2/2] samples/kobject: make attribute_group const

標題標註版本號的方法可以藉由 `git format-patch`，比如要寄送第二版就打 `git format-patch -v2`，生成的 patch file 會自動將標題加上版本號

假如在這之間有需要更動 commit message 的內容，如果是最近的一次 commit 要修改，可以用 `commit --amend`，如果更之前的 commit，要使用 `git rebase`。

#### 未寫 patch 版本變更的簡介
每一次再發送的新版 patch 都必須寫下每一次 patch 版本變更的簡介，我[第二版 patch ](https://lore.kernel.org/all/2025071648-atonable-antihero-2df2@gregkh/)同樣犯此錯。

[PATCH v3 2/2] samples/kobject: make attribute_group const

The attr_group structures are allocated once and never modified at
runtime.  Also to match the const‑qualified parameter of
sysfs_create_group().

Signed-off-by: Meng Shao Liu <[e-mail]>
---
V2 -> V3: Add missing version tag to subject line.
V1 -> V2: corrected my name, thread the patch series, and remove
incorrect commit message "No functional change".

 samples/kobject/kobject-example.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/samples/kobject/kobject-example.c b/samples/kobject/kobject-example.c
...

版本變更簡介一定要寫在 `---` 分隔符的下一行，而簡介內容沒有固定格式，只要能讓 maintainer 清楚了解你每一個 patch 版本的內容和原因就可以。

#### nano 編輯器輸入時的顯示 bug
我的電腦是 Ubuntu 24.04，在撰寫 samples/kobject: make attribute_group const 這個 patch 的 commit message 的時候，nano 編輯器在左下角會錯誤的標示一個紅色區塊，一開始我一直以為是我意外刪除那行的空格才會這樣，結果後來仔細對照 diff 才發現是顯示 bug，不需要管它。

#### 回覆 reviewer
maintainer 如果 review 你發送的 patch，大概率會提建議讓你修改，這時如果要回覆他時，不能使用 gmail，要使用 mutt 進行回覆，而回覆 email 本身並不會影響你 patch 的結構。

使用 mutt 時，如果信箱要使用 gmail 的話，必須在 Google 帳戶申請「應用程式密碼」才能使用。

## 耐心等待結果
最後如果 maintainer 接受你的 patch，他就會寄一封信通知你，這樣就完成了你的工作了，接下就等待通過測試然後 merge 進主線。

我很幸運的是 Greg KH 是很活躍的 maintainer，才能在一天內完成，那如果一些 maintainer 比較忙，可能就要多等幾天。