RT-Thread今天的快速發(fā)展和所取得成績，離不開所有開發(fā)者的持續(xù)貢獻和社區(qū)小伙伴的竭力支持。

一、前言

今年6月，我在一款智能混合型的FPGA芯片上，完成了RT-Thread的移植，并向RT-Thread提交了一個完整的BSP，后續(xù)又根據(jù)審查意見進行了一些完善，最近（11.18）被合并到RT-Thread主分支上。

如果你曾經下載過RT-Thread的源碼倉庫，在最常用的STM32 BSP上面的smartfusion2，這個BSP就是我提交的了，如果有讀者朋友使用過這款芯片，歡迎體驗，或者提交BUG。

有的朋友可能注意到了，我這里使用的是FPGA芯片，F(xiàn)PGA芯片還能運行RT-Thread嗎？準備的說，應該是FPGA片上的處理器可以運行RTOS，這里的處理器，從實現(xiàn)方式來看，包括硬核和軟核處理器；從內核種類上來看，包括ARM核或其他內核，如ARM硬核，Altera的NIOS軟盒，Xilinx的microblaze軟核，還有51軟核等，關于FPGA片上處理器，可以參考以下文章：

• FPGA硬核和軟核處理器的區(qū)別

• 除了ZYNQ還有哪些內嵌ARM硬核的FPGA？

此次提交的這個BSP是我第一次向開源項目貢獻代碼，而且是向這么優(yōu)秀的國產RTOS操作系統(tǒng)，還是很有成就感的~本篇文章記錄如何向RT-Thread或其他開源項目貢獻代碼，有不準確的地方歡迎大家指正，希望大家支持國產RTOS的發(fā)展！

二、RT-Thread遵循的許可協(xié)議

RT-Thread的開源協(xié)議是進行過調整的，在2018年RT-Thread官方公眾號發(fā)布的一篇文章[1]中，我們可以知道當時是使用的GPLv2協(xié)議，

但是現(xiàn)在已經是Apache-2.0協(xié)議了。

在貢獻代碼之前，我們有必要先來了解一下開源項目所遵循的協(xié)議，如果你提交成功，開源協(xié)議將會約束這些代碼被如何使用。從RT-Thread官方GitHub頁面，我們可以了解到RT-Thread所遵循的開源協(xié)議為：Apache-2.0 License，這個協(xié)議有以下特點：

• 永久權利
  一旦被授權，永久擁有。

• 全球范圍的權利
  在一個國家獲得授權，適用于所有國家。假如你在美國，許可是從印度授權的，也沒有問題。

• 授權免費，且無版稅
  前期，后期均無任何費用。

• 授權無排他性
  任何人都可以獲得授權

• 授權不可撤消
  一旦獲得授權，沒有任何人可以取消。比如，你基于該產品代碼開發(fā)了衍生產品，你不用擔心會在某一天被禁止使用該代碼。

有很多人認為開源就是免費，可以隨意的使用，其實這個觀點是錯誤的。如果你有自己的開源項目，關于協(xié)議的選擇可以參考黃工大佬之前總結的[2]：程序猿如何選擇開源協(xié)議？

開源協(xié)議雖然不一定具備法律效力，但是當涉及軟件版權糾紛時，開源協(xié)議也是非常重要的證據(jù)之一。

三、SmartFusion2 BSP簡介

這個BSP是移植 RT-Thread 操作系統(tǒng)到一款 FPGA 芯片——M2S010 ，該芯片屬于 Microsemi（現(xiàn)Microchip）SmartFusion2系列，是一款智能混合型FPGA，片上除了 FPGA Fabric 邏輯部分，還包括一個 ARM? Cortex?-M3 內核的 MCU，主頻最高 166MHz ，256KB eNVM，64KB eSRAM，集成GPIO、UART、I2C、SPI、CAN、USB等基本外設。

關于 Microsemi，第三大 FPGA 廠商，原 Actel 半導體，2010 年，Microsemi 收購 Actel，2018 年， Microchip 收購 Microsemi。

SmartFusion2 內部框圖

移植了 RT-Thread 內核，支持線程調度、線程間同步和通信等，已經完成了PIN、Serial設備驅動，F(xiàn)inSH組件默認使用uart0設備。支持GPIO和UART外設，支持SCons構建系統(tǒng)，可以輸入scons調用env工具中包含的arm-gcc編譯器構建工程，支持以下scons命令：

• scons：使用arm-gcc編譯BSP

• scons -c：清除執(zhí)行 scons 時生成的臨時文件和目標文件。

• scons --target=mdk4：重新生成Keil MDK4環(huán)境下的工程。

• scons --target=mdk5：重新生成Keil MDK5環(huán)境下的工程。

• scons --dist：打包BSP工程，包括RT-Thread源碼及BSP相關工程文件。

通過添加Kconfig文件，可以使用menuconfig來配置外設，用于生成rtconfig.h。

四、如何提交你的BSP包

0.準備工作

進行提交之前，需要做一些準備工作：

• 一個GitHub賬號
• Git Windows客戶 端(git-scm.com/download/win)
• 一些基本Git命令的使用，如 git clone/add/commit/pull/push/checkout等。
• 了解所使用處理器的啟動流程，熟悉基本外設的使用，如GPIO、UART等。

1.Fork并Clone到本地PC

登錄自己的GitHub賬號，F(xiàn)ork RT-Thread倉庫到個人倉庫，F(xiàn)ork的意思可以理解為復制一份。

將遠程倉庫下載到本地：git clone https://github.com/username/rt-thread，這樣就會把遠程代碼下載到本地。

2.創(chuàng)建分支

從 master 分支創(chuàng)建自己的開發(fā)分支，如whik_sf2，可以使用命令：git checkout -b whik_sf2

3.開發(fā)你的BSP包

這是整個開發(fā)過程中最重要，也是最耗時的一步，如果是ARM內核，可以參考STM32的移植過程，如果是其他內核，就需要多用一點時間了。

編碼風格參考：https://github.com/RT-Thread/rt-thread/blob/master/documentation/coding_style_cn.md

一個最基本的BSP包，至少應該包括以下部分：

• 內核移植，支持線程調度、線程間同步和通信

• 支持GPIO/UART外設，PIN/Serial設備驅動

• 支持SCons構建系統(tǒng)，可以使用arm-gcc進行編譯，支持生成MDK工程，支持dist打包，通過SConscript、SConstruct、rtconfig.py文件實現(xiàn)

• 支持menuconfig配置外設，用于生成rtconfig.h，通過Kconfig文件實現(xiàn)

• README文件用于指導開發(fā)者如何使用這個BSP包，可以參考其他BSP文件夾下的README文件

提交關于BSP的代碼，盡量確保代碼改動僅限制于BSP中，而不影響到其他代碼，否則可能會被拒絕[3]。

4.提交到遠程并發(fā)起PR

如果本地進行測試沒問題，就可以同步到遠程了，三部曲：git add/commit/push，更新到遠程之后，就可以發(fā)起PR了，在 git 倉庫中選擇自己修改了的分支，點擊 create Pull Request 按鈕發(fā)起 pull request。

在正式發(fā)起 Pull Request 之前，需要根據(jù) Preview 里面默認的描述信息即 checklist 仔細核對代碼，在沒問題的 checklist 對應選項復選框填寫[x]確認，注意[x]兩邊沒有空格。比如若代碼是成熟版本，請選擇成熟版本，且可以添加相應的描述信息，checklist 核對完成才可發(fā)起 Pull Request。

第一次為 RT-Thread 貢獻代碼需要需要簽署 Contributor License Agreement。

請確認 CLA 顯示簽署成功及 CI 編譯通過，如下圖所示：

提交PR之后，就會獲得一個PR#號碼，在https://github.com/RT-Thread/rt-thread/pulls可以看到所有的PR請求，其中應該會包含你的。如果是Open狀態(tài)，說明正在進行代碼審查，還沒有合并到主分支。

5.代碼審查

一個完善的BSP，往往不是一次性就能提交成功的。提交PR后，要多看看反饋， 項目管理者會對提交的代碼進行審查，如果有問題會在對應的PR下面進行評論，提出修改意見，就像下面這樣：

PR只需要提交一次，每次根據(jù)修改意見進行修改之后，項目管理者會看到你的修改，并再次審查修改之后的代碼，一般需要2個或以上的項目管理者進行審查，如果代碼沒有問題，就可以進行以下步驟了。

6.添加到CI自動化編譯

如果是提交的完整BSP，可以將BSP添加到CI編譯腳本，使用遠程主機對BSP進行編譯，和本地使用arm-gcc scons編譯是一樣的，如果本地編譯正常，這一步基本也會通過。

7.等待合并

如果CI編譯成功，而且審查通過，這個PR會依次被標記為+1、+2，此時只需要耐心等待幾天，直到最終被合并到主分支上。

我提交的這個BSP過程可以參考：

https://github.com/RT-Thread/rt-thread/pull/3661

五、除了代碼還能向開源項目貢獻什么？

為開源項目做貢獻我們可以分為兩大類:代碼類貢獻和非代碼類貢獻。

代碼貢獻

• BUG修復

• 軟件包開發(fā)

• BSP提交

• 內核開發(fā)

非代碼貢獻

• 撰寫和改進文檔

• 通過實例來展示RT-Thread的使用

• 為RT-Thread撰寫教程，如學習筆記、常見問題等

• 官方社區(qū)發(fā)布自己的經驗文章，或積極回復帖子的問題

六、注意事項

• 不要使用非GitHub賬號提交

• 不要使用不同賬號提交Commit之后提交PR，會導致CLA簽署失敗

• 編程風格遵守documentation 目錄下的 coding_style_cn.txt文件。

• 不接受5個以上的Commit

七、總結

向開源項目貢獻代碼，提交PR，可以通俗的理解，這里摘自知乎[4]網(wǎng)友的一段解釋：

我嘗試用類比的方法來解釋一下pull reqeust。想想我們中學考試，老師改卷的場景吧。你做的試卷就像倉庫，你的試卷肯定會有很多錯誤，就相當于程序里的bug。老師把你的試卷拿過來，相當于先fork。在你的卷子上做一些修改批注，相當于git commit。最后把改好的試卷給你，相當于發(fā)pull request，你拿到試卷重新改正錯誤，相當于merge。

當你想更正別人倉庫里的錯誤時，要按照下面的流程進行：

先 fork 別人的倉庫，相當于拷貝一份別人的資料。因為不能保證你的修改一定是正確的，對項目有利的，所以你不能直接在別人的倉庫里修改，而是要先fork到自己的git倉庫中。clone 到自己的本地分支，做一些 bug fix，然后發(fā)起 pull request給原倉庫，讓原倉庫的管理者看到你提交的修改。

原倉庫的管理者 review 這個 bug，如果是正確的話，就會 merge 到他自己的項目中。merge 的意思就是合并，將你修改的這部分代碼合并到原來的倉庫中添加代碼或者替換掉原來的代碼。至此，整個 Pull Request 的過程就結束了。

參考資料

[1]. 如何開啟RT-Thread社區(qū)貢獻之路
https://mp.weixin.qq.com/s/JfVYB0yUcbyxa5EVWY4DKw

[2]. 五種開源協(xié)議(GPL,LGPL,BSD,MIT,Apache)

https://www.oschina.net/question/54100_9455

[3]. 在Github上為RT-Thread貢獻代碼，為自己的人生涂色
https://mp.weixin.qq.com/s/pPGunFzGcfz01pugNnWCiA

[4]. GitHub 的 Pull Request 是指什么意思？
https://www.zhihu.com/question/21682976