开源的一大乐趣就是任何人都可以参与其中。试想下一个流行的项目就有你贡献的代码,是一件多么爽的事情!你可以帮助项目健康发展,添加你希望添加的功能,以及修复你发现的BUG。
作为全球最大的开源社区GitHub,是通过pull request这种形式向上游仓库递交补丁的。具体的操作流程去看github官方文档就好了。这里谈谈如何递交一个漂亮的pull request。
混迹github已经有 好几年的光阴,大大小小的pull request被合并的也有好几十个了,总结下个人的经验,哪些pull request能更加获得青睐,相信把握这几个要点,你的代码被上游合并的几率将大大提高。
详细阅读contribution guide
大多数大型的开源项目都会有一个Contribution Guide的文档说明,里面记录贡献代码的格式和规范。如果你要发起pull request的项目中包含这个文档,那么请务必按照文档上的格式规范化你的pull request,否则很可能被项目维护人员拒绝的。
对于没有这种文档的开源项目,基本上把握以下几个原则,也是非常容易被合并的。
git commit记录保持一致性
在递交代码之前看看git log
的输出,看看历史递交记录中的commit记录是怎么写的,最好语法上保持一致性。有些项目是非常看中commit记录的一致性和规范性的,比如Angular
项目,就是通过commit记录拉取release notes的,不符合commit规范的pull request很可能被直接打回。
对于格式要求没有那么严格的项目,基本上可以从历史commit里面拷贝一个跟你的递交内容差不多的commit记录,稍微做下改动就可以了。
代码风格一致性
这个可以说是开发者最为看重的一个因素。和原风格不符的PR几乎百分百被直接打回。每个人可能都有自己喜好的代码风格,但是切记,pull request一定要按照上游仓库的风格来。
比如我这个pull request,因为风格不一致就被作者抱怨过(作者使用的是<tab>符缩进,而我的PR使用空格缩进)。
代码质量不能太差
这个和上面那条很多地方是相通的,就是都要阅读一下别的几个代码文件,确定一下代码风格,以及有没有你需要用到的函数/方法,这样你就不用再写很多冗余代码了。同时,代码风格上的一致性也可以最大限度的避免烂代码的存在。
Pull Request信息规范化编写
很多开源项目可能已经定义好了issue和pull request的模板,照着填写就好了。对于没有模板的项目,可以看看已经合并的PR的信息是怎么写的,参照就可以了。
如果没有合适的参照,至少按照条目列清楚你做了哪些修改,以及修改的目的(实现什么功能?或者修改了什么样的BUG,并给出对应的重现方式,如果已有issue反馈这种问题,当然直接引用issue链接就好了)
限制pull request的规模
不要在单一的pull request做大规模的改动,这样会带来审核代码的困难性,也许你的PR会因此反馈周期被无限制的拉长。印象中微软曾经给node js递交过一个超大的pull request,几乎每个代码文件都有改动。结果引来上千项目维护者的围观,共同审阅了大半年。
如果你希望你的pull request被尽快合并,那么不应该改动太多才发起PR。应该每个小改动就发起一次PR,尽快得到上游开发者的审阅。
确保测试必须通过
某些开源项目有自动化测试的步骤,通常是通过Jenkins或者Travis CI等工具自动触发自动化构建的。测试失败的代码几乎不会通过审核,所以这个也是务必要注意的。绝大多数开源项目都会有命令行工具跑自动化测试,如mvn test
/ gradle test
/ make test
等等。如果你不确定代码是如何运行自动化测试命令的。那么可以点击进入ci robot提供的地址,看看自动化测试工具打印在终端上的命令,本地跑一下那个命令运行测试即可。务必确保本地测试能通过之后再递交pull request。
基本上按照以上几个原则递交pull request,那么你的代码被合并的几率将大大提高,共同享受开源带来的乐趣吧。:)