提交第一份 Patch 到 Linux Kernel

contributed by < steven1lung >

我自己的心得

在看老師的書 Demystifying the Linux CPU Scheduler 的時候，突然好奇說每一個任務的 loading 是如何運算的，畢竟排程器上的任務如此多，計算出 load 然後依據每個 CPU 的狀態去做 task migration 應該是很重要的課題。所以我就跑去 pelt.c 看了一下實際的運算是如何做到的。

pelt 全名是 Per Entity Load Tracking

在看程式碼的時候，發現有個地方的中括號打反了變成 [1002..1024[，我就想說試試看發人生第一個 patch。

結果自己在摸索如何發 patch 花了好多時間…，轉眼間就早上了。所以就記錄了一下自己發 patch 的過程來紀念逝去的時間。雖然這個 patch 最後是我誤會中括號的用法，所以並沒有被採納，但跟這些厲害的人交流讓人有點興奮><

結果發現反過來的中括號是法文的用法，是我自己搞錯 xD

我發的 patch 在這裡。

前言

Linux Kernel 的開發跟維護方法是透過信件來溝通跟 review，Linux Kernel 有一個龐大的 mail server，每天收到近千個信件提交 patches，格式不正確或是表達不好的 patch 很常會被忽略，連回覆都不會有，所以要如何寫好一個好的 patch 充滿學問。

“Only wimps use tape backup. REAL men just upload their important stuff on ftp and let the rest of the world mirror it.” –Linus Torvalds

準備提交 Patch 會使用到的 Email Client

• git send-email
• mutt

git 其實就有提供一個命令：git send-email 來做到發出信件的功能，或是也有很多人會使用 mutt 來幫忙發 plain text mail。我自己是 send patches 時會使用 git send-email，如果只是回覆 comment 之類就會用 mutt。

這邊要小心如果回覆 patch 的 comment 的時候使用 gmail 或是手機內建的信箱，要記得信件不要使用到 html，會被 lkml 認為是 spam 或病毒，就會被退回。

git send-email

使用之前還需要到 ~/.gitconfig 裡先設定一些 smtp 的資料：

$ vi ~/.gitconfig

然後在最後面加上：

[sendemail]
        smtpencryption=tls
        smtpserver=smtp.gmail.com
        smtpuser=你的信箱@xxxx.com
        smtpserverport=587
        smtpPass=你的APP密碼   

APP 密碼的設定方式在下面有說明。

mutt

mutt 是一個很多開發者都會使用到 mail client，Greg Kroah-Hartman 也是使用這個！他也有在網路上分享自己的 workflow，詳情可以看這裡。

mutt 並不是內建的，所以事先需要安裝：

$ sudo apt install mutt # Debian 
$ sudo dnf install mutt # Fedora
$ brew install mutt # Macos

接著一樣要去設定一些 smtp 的參數：

$ vi ~/.muttrc

把以下的資料填好並且儲存：

set ssl_starttls=yes
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

App 密碼設定

因為我信箱是使用 gmail，這邊就放我是如何設定 gmail 的。其中 你的APP密碼 需要到 gmail 裡面設定一個給應用程式的密碼，步驟如下：

https://support.google.com/mail/answer/185833?hl=en

1. 開啟 google 的 2FA 認證

   到 這裡 的 「登入 Google」點選兩步驟驗證，並且完成設定。

2. 建立應用程式密碼

   「開啟兩步驟驗證」的下方有一個「應用程式密碼」，點進去後選擇「郵件」跟「其他」，名字就取一個自己會認得的就可以，完成後會顯示密碼，複製貼到 .gitconfig 或是 .muttrc 就可以了。

在本地端建立一個 Repo

如果直接去 github 上 clone 會花很長的時間，這裡我是到 release 找最新的檔案下載，之後再解壓縮就好了。

這裡舉我下載的 linux-5.19-rc1.tar.gz 為例，載完後將檔案解壓縮到想要開發的目錄下：

$ tar -zxvf linux-5.19-rc1.tar.gz

之後就可以進去設定 git：

$ cd linux-5.19-rc1
$ git init
$ git add .
$ git commit -m "origin"
$ git checkout -b my-patch

如果是第一次使用 git 也要記得先git config 設定一下名字跟信箱喔！

之後就可以進行修改了！

Commit Message

完成自己的修改後就可以新增 commit：

$ git commit -asv

-a：加入剛剛修改並且有 track 的檔案
-s：commit 會加上 Signed-off-by: <你的名字> <你的信箱@XXX.com>
-v：verbose，會列出你的修改，看著寫 commit message 會比較方便

commit message 格式

Patch 的格式都有嚴格的限制，沒有寫過的同學可以去看你編輯的檔案之前 commit 是如何寫的比較有概念。

簡單來說就是會分成：標題、內容描述、自己的簽名，中間都會空一行：

subsystemName: short description
# blank line
patch content description
# blank line
Signed-off-by: "name" <email>

建立 Patch

完成 commit 就可以建立等等要寄出去的 patch 了：

$ git format-patch master

建立好的 patch 要先通過一些 scripts 裡面的檢查：

$ ./scripts/checkpatch.pl ./patch_name.patch

如果你的 patch 有問題，會有提示訊息跟你說是哪裡需要修改，修改完後可以使用：

$ git commit -a --amend
$ git format-patch master

寄送 Patch

接著就要找出 maintainer 是誰，並且將 patch 寄給他，這邊舉修改 docs 為例：

$ ./scripts/get_maintainer.pl ./patch_name.patch

Jonathan Corbet <[e-mail]> (maintainer:DOCUMENTATION)
[e-mail] (open list:DOCUMENTATION)
[e-mail] (open list)

從輸出就可以看到要寄給的人了，通常裡面的人都會要 CC 到。

使用 git send-email：

$ git send-email --to [e-mail] \
--cc [e-mail] \
--cc [e-mail] \
./patch_name.patch

使用 mutt：

$ mutt -H ./patch_name.patch

後續

之後就可以到 lkml.org 看看有沒有出現你的 patch 了，靜靜等待 review 就好了。

後記

之後在看 UML (User Mode Linux) 的時候找到一個錯字，也順手送了一個 patch 過去，document 的維護者 Jonathon 還恭喜我發送第一個 kernel patch，人真的很好 xD

Jonathon 的回覆