向 Linux 核心上游提交更動 - 蔡鎮宇
======

{%hackmd @coscup/BkyL5IdFA %}

> 請從這裡開始

[TOC]

## 為什麼會需要提交貢獻

## 提交前的準備工作

### 準備電子信箱

* 跟上游做互動
* 必須能收到信
* 電子郵件客戶端：
* 不能竄改寄出的郵件內容（如機密資訊警告文字）
* 必須支援寄送純文字信件
* {郵件論壇|mailing list}：
* 吁噓ˋ
* 不收 HTML 信件
* 不收郵件附件
* 部份郵件論壇需要訂閱才能發布內容

### 抓取最新的程式碼

* 必須基於最新的版本
* 不要使用 `git clone`，直接下載打包好的 Git 版控庫以減輕伺服器的負擔
* 可以提交的地方：
* 上游主線（Linus Torvalds 的 repo），可以提交一些希望可以早一點被合併的 patch。
* 下一大版的整合樹(linux-next)，主要負責提交一些新功能之類的東西
* 也可以看看子系統的維護者，去發到他們自己的 repo

### 詳細描述所作的更動

* 訊息要求滿多的
* Subject 的描述越 specific 越好 Example: https://patchwork.kernel.org/project/linux-mediatek/patch/[e-mail]/
* 重點在*為甚麼要做這個更動*。
* 想要加入的功能。
* 相關的背景：
* 像是 bug 的重現，什麼樣的硬體，什麼樣的條件會發生。
* 或是效能的改善，可以改善多少等數據。
* 設計上的妥協，為甚麼要這樣子做設計，其他的設計有沒有甚麼問題等。
* 有沒有需要其他更動輔助，或是基於其他更動的 base。
* 加上 Fixes: _commit hash_
* 考慮是否需要向前移植到穩定版上
* 記得{簽名|sign-off}：知道你的貢獻是你寫的會有收到發表授權

### 拆分所做的更動

* 不會說一整坨東西直接打包送出去
* 一個 commit：邏輯上的一件事情
* 修改程式介面、函式參數等
* 程式碼原封不動的搬移
* 修正錯誤
* 加入新功能
* 對多個檔案做同樣的修改

### 檢查更動
* 檢查 coding style，目前沒有自動化的工具在做這件事。
* 務必直接引用對應的標頭檔，不要依賴別人的依賴。標頭檔有時候會被拆分，這樣就會爛掉。
* 使用 barrier 務必加註式解釋用途。
* 執行自動化檢查
* `scripts/checkpatch.pl --strict <patch_file_path>`
* sparse 工具檢查
* 靜態分析軟體，做一些基本的檢查
* make C=1

### 檢查更動 - Device Tree 限定

* 檢查規範文件的修改式是否正確
* 檢查 Device tree 是否符合規範文件
* 有規定的 coding style

### 測試做好的更動
* 測試非常重要，大家都寫得 code 都不完美
* 至少要可以編譯，不能編會直接被黑掉
* 有加設定參數要實驗開跟關都可以編過
* 做硬體支援的話，一定要經過測試，畢竟不能把人家的機器燒壞。
* 不可以弄壞別人的機子
* 韌體/應用程式界面必須向前相容，不是所有人的機器都會即時做更新

### 生成補釘信件並送出

* `git format-patch`：生成補丁，絕對不適用其他指令在複製貼上
* `git send-email`： 用這個來寄出補釘文件
* 需要設定 SMTP 伺服器及認證資訊
* patch 超過一個必須寫說明文件
* `git format-patch`加上`--cover-letter`可以連帶生出範本

[Comparing and Contrasting Patman Vs B4 for Posing Patches - Doug Anderson, Google](https://www.youtube.com/watch?v=7B3nKmBoFoQ)
## 補丁寄出後

### 等等等

* 大家都在其他時區啦，等個 1-2 天是很正常的。
* 亞洲時區的維護者非常非常少
* 有些貢獻可能需要等其他人回饋，
* 維護者也可能會去度假啦，他們會直接消失
* 感恩節、聖誕假期
* 暑假
* 大家都是志工，可能不一定會是全心全力在做這些事，就是要等他們啦
* 沒有回應的話可以 ping
* 有的會希望回復原信件去詢問
* 有的會希望直接重送，因為他可能把原本的信刪掉惹

### 收到回應 - 有錯誤
* checkpatch 錯誤
* 盡量避免
* Does not apply - 無法套用
* 選錯基底版本
* 有發生衝突：rebase 之後再重送一次
* Build error
* 盡量避免
* 修好後再送一版

### 收到回應 - NAK

* 維護者強烈反對
* 大家有各自的考量
* 不適所有的人都喜歡
* 思考並與社群討論更適合的解法

### 收到回應 - Looks good, but...

* 審核者覺得還有改進空間
* 意見都盡量要回應
* 不要忽略審閱者的提問
* 要不然有的人會覺得在浪費時間

### 收到回應 - Applied

* 過幾天看看維護者的 repo 有沒有出現你的貢獻

### 回信注意事項

* 不要動 In-reply-to 的標頭
* 回信也是用純文字
* 原文字不要刪掉

### 回文接在原文下方

* 回文回在 quote 下方
* 跟對話類似

### 再送新的一版

* `git format-patch -vN`
* 說明新版有什麼變化
* 需要附審核者的 Reviewed-by
* 不要一天送好幾個版本，這樣等於在轟炸別人的信箱

### 社群、維護者、審核者、貢獻者、使用者

* 大部分都是志工，大家都不是全職在座，大家就是希望 linux 更好。
* 不要浪費他人的時間，測試要好好做，不要把其他人當作人體 debugger。
* 審核者就是把關和新的設計和架構同時接收大家的貢獻，他們也沒辦法馬上處理
* 貢獻目的不要惡意欺騙維護者
* 社群以線上參與為主。
* 如果有機會去參加實體研討會，強烈推薦大家參與，台灣人真的不多