讓您的程式碼回歸 Linux 上游源頭進行更新：入門篇（原載於OpenFoundry法律源地）
© 2011，著作權所有。作者：Armijn Hemel & Ralf Baechle；譯者：林誠夏、葛冬梅、Ant。
此中譯版之授權條款為：創用CC – 姓名標示 – 禁止改作 3.0 台灣。
這份文件描述的內容是，晶片製造商需要採取哪些步驟，讓他們的程式碼成功地回歸 Linux 核心的上游開發主幹（mainline）進行更新。
為什麼要讓程式碼回歸上游源頭進行更新？
讓程式碼回歸上游源頭進行更新可以帶來各種不同的好處：最重要的是，您所修改的程式碼可以被更多人看到。將您所修改的程式碼儲放在某些 FTP 上讓人下載，其能見度必然會低於置放於 Linux 核心的開發主幹上。而如果程式碼是放置於 Linux 的核心主幹，這會更有助於其他人取得這些程式碼並下載利用，並使您所生產的晶片組或是主機板更具使用上的吸引性。此外，這也將會便利他人改良您的程式碼，並有助於該程式碼能一直保持在最新的更新狀態（Linux 核心的程式碼會經常地被更新修改）。
將您的程式碼回歸到上游源頭進行更新，並不代表其他程式開發者，會從程式碼上傳的第一天開始，就為您撰寫改良這些程式碼。至少在上傳這些程式碼的初期時，在程式開發上面投注最多時間成本的人將還是您本身。而儘管短期來說，您可能還需要花費一些額外的工程資源在程式的開發上，但是從中長期來看，讓程式碼回歸到 Linux 核心的上游主幹絕對會為您帶來值得的回報。
如何與 Linux 核心的上游開發者溝通
Linux 核心的社群開發者針對許多開發事項都已經有了成熟的運作規則，例如：程式碼的撰寫風格（coding style）、開發者彼此間的連絡溝通方式等等。很多 Linux 核心的主要開發者都非常忙碌，因此在與這些人打交道時最好能遵循這些既定規則，以讓整個溝通流程可以儘可能地順暢進行。
適當調節您的個人期待
您第一次提交給 Linux 核心開發者的程式碼，有可能不會被接受，不被接受的原因可能基於不同的理由，例如：程式碼不符合既定的撰寫風格、程式碼的品質不如預期等等。不過請不要將這樣的回應視為您的程式碼被拒絕了，而是要將這些互動視為將您的程式碼成功匯入 Linux 核心主流的第一步。
有時候這些 Linux 核心開發者對您的回應可能非常簡要，或者看似急躁與不耐煩，同樣地，請不要將這樣的回應視為您的程式碼被拒絕了，這其實是您還需要多加些努力的信號。
準備與提交您的程式碼
將程式碼上傳回 Linux 核心主流的提交與準備工作文件，已經被整理在 Linux 核心源碼目錄下的這些位置：
* Documentation/CodingStyle
* Documentation/SubmitChecklist
* Documentation/SubmittingDrivers
* Documentation/SubmittingPatches
一般來說，程式碼的提交步驟要從程式碼的清整與格式調整開始，提交者要先將程式碼的格式調整到與「CodingStyle」目錄裡的指示文件相符。然後依據「SubmitChecklist」目錄裡的提交清單逐項檢查，餘下「SubmittingDrivers」與「SubmittingPatches」這兩個目錄的文件，則是存放實際提交步驟的說明文件。
當您根據目錄裡的撰寫標準調整完所欲提交的程式碼後，下一個步驟就是將這些程式碼分割為適當大小的修補程式（patch）以利提交。這是因為當修補程式的檔案過大時，會造成他人難以檢閱的結果，所以最好是將修補程式維持在合理的容量內。這樣處理的另一個好處在於，適當分割後的修補程式將可以獨立地被不同的 Linux 核心開發者檢閱，例如以下的範例事項，都適合分割為個別獨立的修補程式來進行提交：
– 修正程式特定的問題
– 修正特定的拼字錯誤
– 修正 Linux 核心裡許多地方都會發生的共同問題
– 新版的硬體驅動程式
– 增加對新式系統晶片（SOC）或是評估板的相關支援
修補程式的提交應以上述建議的方式進行，這樣才能確保這些修補程式被納進 Linux 核心時不會破壞了系統的運作，即便是暫時性系統失靈的狀況都得盡量的避免，因為這會使得故障排除的工作變得更為困難。Linux 核心是利用「git-bisect」這隻程式進行故障排除，而若是某個版本的 Linux 核心發生系統失靈的狀況，即使這僅是暫時性的失靈，都會讓「git-bisect」的運作變得非常困難，或者根本無法運作。
當您完成了程式碼的清整工作，依照「CodingStyle」目錄裡的文件進行格式調整，並依其性質適當地分割為獨立的修補程式之後，接下來便可以將這些修補程式發送出去了。如果這些修補程式是為了增加新作業系統或系統晶片的支援，所影響的層面會觸及到 Linux 核心數個不同領域，但這並不代表您需要將這些修補程式發送給 Linux 核心郵件列表上的每個人。舉例來說，ARM Linux 的維護成員們對於針對 MIPS 所撰寫的程式碼並不會太感興趣。若是您想要了解如何將程式碼發送給 Linux 核心適合的開發成員，Linux 核心源碼樹狀目錄下「MAINTAINERS」這個檔案，能協助您了解相關資訊。
舉例來說，「MAINTAINERS」這個檔案裡您可以找到 squashfs 程式的相關資訊有：
M: Phillip Lougher
W: http://squashfs.org.uk
S: Maintained
F: Documentation/filesystems/squashfs.txt
F: fs/squashfs/
「L」指向針對 squashfs 這個特定子系統建立的郵件列表，「M」代表 squashfs 主要維護成員的個人連絡信箱或是群組成員的共同連絡信箱。有時您會找不到個別專案的郵件列表或是專案成員連絡信箱的資訊，而若二種資訊都找不到的話，建議您再直接利用 linux-kernel@vger.kernel.org 這個信箱來發送您所欲提交的修補程式。
如果您遵循上述這幾個簡單規則，那麼讓您的程式碼回歸 Linux 核心上游進行更新應該就不會是一件難事。最後、我們想要提供您一個重要的建議：如果您對於向 Linux 核心上流提交程式碼這件事有任何的疑問，儘管向這些 Linux 核心的開發者提出您的疑問。一般來說，這些 Linux 核心的開發成員，將會非常樂意地回答您所提出的相關問題。
———-
Upstreaming your code – a primer
Copyright © 2011 Armijn Hemel & Ralf Baechle .
This work is available under the Creative Commons Attribution-No Derivative Works 3.0 Unported license.
This document describes what steps chip vendors need to take to successfully upstream their code into the mainline Linux kernel.
Why upstreaming?
Upstreaming code has various advantages: the code will be seen by more people. A “code dump" on some FTP site will be less visible than code in the mainline kernel. If code is in the mainline kernel it will be more readily accessible and usable by more people, making your chip or board more attractive to use. It will be easier for others to improve the code and keep it up to date (code in the Linux kernel is frequently reworked).
Upstreaming your code does not mean that people will write the code for you from day 1. The biggest investment in engineering will, at least initially, still come from you. While there might be some additional costs in the short term in the form of engineering resources, upstreaming will definitely pay off in the mid to long term.
Communicating with upstream
The Linux kernel community has its own set of rules regarding various things, such as coding style, communication, and so on. Many of the leading developers in the Linux kernel community have little time, so it is best to follow these rules to make the whole process as smooth as possible.
Managing expectations
It is likely that the first submission to a Linux kernel developer of your code will not be accepted. This could be for various reasons: the code does not follow the coding style, code quality might not be as high as is expected, and so on. Do not see this as a rejection of your code, but as a first step for successful inclusion into the mainline kernel.
Sometimes developers might react very terse, or seemingly irritated. Once again, do not see this as a rejection, but as a sign that you need to put in a little bit more effort.
Preparing and submitting your code
The rules to follow have been documented in the Linux kernel source archive at the following locations:
* Documentation/CodingStyle
* Documentation/SubmitChecklist
* Documentation/SubmittingDrivers
* Documentation/SubmittingPatches
Typically the submission process starts with cleaning up your code and formatting it to comply with the rules as outlined in the document “CodingStyle". A list of items to check for in the code is in “SubmitChecklist"; the remaining two files document the actual submission process.
Once the code has been adapted according to the coding standard, the next step is to split up the code into patches for submission. Because very large patches are harder to review it is best to keep patches reasonably small. Another benefit is that this way the patches can be reviewed independently. Some examples of what are good things to keep in one separate patch:
– fixing a bug
– fixing a spelling mistake
– a bug fix for the same bug that appears in several places in the kernel sources
– a new driver
– support for a new SOC or evaluation board
Patches should be split in such a way that when they get applied to the kernel they do not break anything, not even temporarily. This is because it makes debugging a lot harder. Debugging the Linux kernel is done using “git-bisect". If a version of the kernel is broken, even if it is temporarily, the use of git bisect is significantly harder or even impossible.
After you have cleaned up the code, adapted it according to the right coding style and split it up into proper patches it is time to send out the patches. Support for an entire new system or SOC will touch several areas of the kernel, but it is not necessary to send all the patches to everybody on the Linux kernel mailinglist. For example, the maintainers of ARM Linux will not be very interested in MIPS specific code. The MAINTAINERS file in the kernel source tree can help you with this.
As an example, for the squashfs code you would find:
SQUASHFS FILE SYSTEM
M: Phillip Lougher
W: http://squashfs.org.uk
S: Maintained
F: Documentation/filesystems/squashfs.txt
F: fs/squashfs/
‘L’ points to the mailing list for the specific subsystem. ‘M’ indicates the direct contact address for the maintainer or maintainers. In some cases one of these might be missing. If both are missing you should use linux-kernel@vger.kernel.org to send patches to.
If you follow these simple rules upstreaming your code should not be much of a problem. One important piece of advice that we want to give you: if you have questions, simply ask them. The Linux kernel developers will be more than happy to answer your questions.
