owned this note   changed 2 months ago  
Linked with GitHub

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

歡迎來到 https://hackmd.io/@coscup/2024 共筆 :mega:
點擊本頁上方的 開始用 Markdown 一起寫筆記！
手機版請點選上方 按鈕展開議程列表。

請從這裡開始

為什麼會需要提交貢獻

提交前的準備工作

準備電子信箱

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

抓取最新的程式碼

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

詳細描述所作的更動

  • 訊息要求滿多的
  • Subject 的描述越 specific 越好 Example: https://patchwork.kernel.org/project/linux-mediatek/patch/20240801031030.31114-1-yr.yang@mediatek.com/
  • 重點在為甚麼要做這個更動。
    • 想要加入的功能。
    • 相關的背景：
      • 像是 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

補丁寄出後

等等等

  • 大家都在其他時區啦，等個 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。
  • 審核者就是把關和新的設計和架構同時接收大家的貢獻，他們也沒辦法馬上處理
  • 貢獻目的不要惡意欺騙維護者
  • 社群以線上參與為主。
  • 如果有機會去參加實體研討會，強烈推薦大家參與，台灣人真的不多
Select a repo