如何給 GNU 項目貢獻代碼
本文以Emacs項目為例。
1 訂閱郵件列表
GNU的項目都通過郵件列表和全世界的貢獻者交流,所以你應該先去 https://lists.gnu.org/mailman/listinfo 找到相應項目的郵件列表。一般建議加入bug和devel兩個郵件列表。比如Emacs,找到Emacs-devel和bug-gnu-emacs郵件列表并訂閱,前者用于討論改進、提新的feature等,后者用于反饋bug、提交patch。
郵件列表的郵件量一般都比較大,尤其是加入了多個項目的郵件列表后,不僅信息多,還很雜亂,所以建議:
1、 建立文件夾,如圖,QQ郵箱:
2、 做收信規則,根據收件人規則把郵件移動到相應的文件夾中。如圖,QQ郵箱:
2 修改代碼
GNU項目有自己的代碼倉庫,在這里:https://savannah.gnu.org/ 。
找到Emacs的Git倉庫:http://git.savannah.gnu.org/cgit/emacs.git
然后把代碼拉回本地:
$ git clone git://git.sv.gnu.org/emacs.git -b emacs-25
Emacs有很多分支,目前的開發主要在emacs-25這個分支上進行,所以上面命令我是從emacs-25分支上拉取的代碼。
一段時間后維護者會把代碼合并到master分支中。
如果之前已經拉過代碼了,在修改前記得pull一次來保持代碼是最新的:
$ git pull
不要在當前分支上修改代碼,理由有很多,比如官方不一定接受你的patch。而是對每修一個bug都新建一個分支:
$ git checkout -b tramp-sh-add-doas --track emacs-25
這行命令我新建了一個叫”tramp-sh-add-doas“的分支,取名要有含義,尤其是你在要修復多個bug時好區分。這個名字的含義是為了在tramp-sh里增加doas命令的支持。
接下來是漫長的編碼階段,主要注意兩點:
編碼風格統一,最簡單的方法就是看看同文件里別人是怎么寫的,他的縮進、命名、花括號位置等等。
不要去修改無關的代碼,比如去動了其他位置的縮進等等。不然維護者會很疑惑。
代碼寫完后,commit一下:
$ git commit -a
寫一段好的commit也很重要,最簡單的方法就是執行git log,看別人怎么寫的。一般commit的第一行寫清楚你本次修改是做了什么,再空一行,逐行列出增加、修改的函數和變量等,讓開發者一目了然,比如:
Author: Xi Lu <lx@shellcodes.org> Date: Fri Dec 11 10:52:08 2015 +0200 Initial support for Ruby in 'etags' * lib-src/etags.c <Ruby_suffixes>: New variable. (lang_names): Add an entry for Ruby. (Ruby_functions): New function. (Bug#22116)
提交commit后,執行以下命令生成一個patch文件:
$ git format-patch emacs-25
這行命令會把當前分支修改的內容和emacs-25分支做diff,然后在當前目錄下生成一個diff文件,如:0001-Add-support-for-doas-command.patch。
生成的patch文件是需要發到郵件列表里,相關文件的維護者會跟你溝通并合并到代碼倉庫中的,和Github上直接發Merge Request來比,就沒那么幸福了。
最后,把補丁發送到郵件列表去(這里或許你需要配置一下Git的發送郵件,請自行找資料):
git send-email --to=bug-gnu-emacs@gnu.org 補丁文件1 補丁文件2 補丁文件..
之后GNU的bug跟蹤系統會確認你的bug,并給你提交的bug分配一個ID,然后自動回復一封郵件給你:
然后就等待相關維護者回復郵件與你溝通。在和開發者溝通時就事論事,不要說無關的廢話。另外一定要注意回復郵件的風格,社區一般使用的Bottom- posting(下回復)風格,實際上很多開源軟件都是用的Bottom-posting風格的。如果這方面你不熟悉,請參考維基百科學習一下:https://zh.wikipedia.org/wiki/%E5%9B%9E%E5%B8%96%E9%A3%8E%E6%A0%BC 。QQ郵箱網頁版是不支持下回復的,最好用郵件客戶端來回復,一般郵件客戶端是可以設置成Bottom-posting風格的,請Google自行查閱設置方法。
開發者和你進一步溝通,完畢之后會關閉這個bug,并把代碼合并到倉庫中去。
你的代碼在合并到倉庫之前可能還會有一道障礙,直到清除障礙后代碼才可以進入倉庫——簽協議。
3 簽署協議文件
如果你貢獻的代碼超過15行(見:https://www.gnu.org/prep/maintain/html_node/Legally-Significant.html ),是需要和FSF(自由軟件基金會)簽紙質協議的。
簽協議的主要目的是證明代碼由你所寫,沒有侵犯到其他版權,并且版權歸給FSF。
如果你提交的代碼確實需要簽文件,開發者會郵件回你一個申請表模板,讓你按模板內容填寫一封申請郵件給FSF來申請簽協議文件的。
模板內容如下(注:“#”是我自行添加的注解):
---------------------------------------------------------------------- REQUEST: SEND FORM FOR PAST AND FUTURE CHANGES [What is the name of the program or package you're contributing to?] # 你貢獻的項目名稱,比如Emacs。 # 注意一個項目只能簽一份協議,如果你這里寫多個項目,就需要簽多份協議。 [Did you copy any files or text written by someone else in these changes? Even if that material is free software, we need to know about it.] # 解釋你貢獻的代碼里是否用了其他項目代碼,如果有就列一下。 [Do you have an employer who might have a basis to claim to own your changes? Do you attend a school which might make such a claim?] # 是不是以你個人名義來提交代碼的,是的話就寫no。 # 如果是公司名義,好像需要公司和FSF再簽協議,這個流程我不熟悉。 [For the copyright registration, what country are you a citizen of?] # 一般就寫China。 [What year were you born?] # 你生日。 [Please write your email address here.] # 你郵件地址。 [Please write your postal address here.] # 通信地址,需要寫詳細點。 [Which files have you changed so far, and which new files have you written so far?] # 你改變了哪些文件,列出來。
把這封郵件發給copyright-clerk@fsf.org, 郵件標題是你真實的姓名 ,郵件內容就是上面模板填寫后的內容。
然后FSF會審核你的申請,一般需要幾天。審核通過后他們回給你發一封郵件,讓你將附件的PDF文件打印下來,然后簽字,簽上你的名字(不要用中文),以及寫好日期(日期的月份需要用英文,不要用數字,如:2015 December 30)。
接下來,把簽完的紙質協議寄到美國去。你可以去淘寶找DHL快遞代收,DHL大概3天就到了,費用大概是¥140~¥160之間。
他們收到你的紙質協議后也會簽字,需要等幾天,具體周期視他們處理情況而定,如果你等了兩周都還沒回你,那么你可以回郵件問問怎么回事,比如我的就正好遇到圣誕節放假。
最后,他們會把簽字后的掃描件以PDF格式發送到你的郵箱,整個過程算是結束了。
如果你換了工作,也請告知他們,有可能會涉及到協議重簽,比如你到了新公司,給他們提交的代碼不再是個人性質。
Happy Hacking。
4 感謝
Xue Fuqiao、Eli Zaretskii
原文出處:http://www.shellcodes.org
來自: http://www.oschina.net//news/70623/contribute-code-to-gnu-project