如何给 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