如果足够幸运,在深入使用 Apache Hive 的过程中会发现引擎bug。向开源社区做贡献,提高公司影响力是引擎维护工作的重要KPI。本文总结下如何向社区提patch,贡献自己的力量。
参考翻译自官网,英语好的话,略过本文,可以直接参考官方文档:https://cwiki.apache.org/confluence/display/Hive/HowToContribute
1 前期准备
首先,应该下载一份hive源码(或者fork一份),并在本地环境开发工具(推荐使用idea)中导入代码环境,并可以成功编译。
如果只是阅读源码,则直接下载hive源码即可(如果想要贡献patch给社区,则fork源码即可):
1 | git clone https://github.com/apache/hive |
编译:(不再支持hadoop 1.x版本,所以以后直接使用hadoop-2编译即可)
1 | mvn clean package -DskipTests -Pdist -Phadoop-2 |
Hive社区采用JIRA维护,在如下链接中注册一个Apache账号,这个账号用来提交issue和patch。
1 | https://issues.apache.org/jira/secure/Signup!default.jspa |
至此,准备工作做好了。然后你可以进行源码阅读和修改,并向社区贡献patch。
2 源码修改
在你发现源码bug之后,首先需要自查。也就是说在社区JIRA中查找是否已经被修复。如果没有查到相关修复或讨论的issue,那么,很荣幸,你很有可能是bug的第一位发现者。
然后,你需要在JIRA中创建一个issue,将该bug报告给社区,当然如果你有修复建议和修复patch,也可以一并提交。之后往往需要耐心等待社区同学对该问题的跟进分析和反馈。
如果,该问题确实是一个新的bug,你可以尝试提交patch。这里需要注意一些代码规范。
2.1 编码规范
这里建议导入源码之后,设置社区的格式化文件:eclipse-styles.xml
设置方法: Settings -> Editor -> Code Style -> Java -> Scheme; 点击管理(齿轮图标); Import eclipse-styles.xml.
- 所有的公共类和方法必须有注释
- 在代码注释中不允许使用作者标签(哈哈,这往往是新手容易犯的错误):@author
- 代码缩进使用2个空格,而不是4个空格
- 单行的长度限制是120个字符
- 贡献代码不能引入新的Checkstyle 禁止规则
- 检查是否引入新的规则方式:mvn checkstyle:checkstyle-aggregate ,最后在 target/site 目录下查看检查结果。
- 贡献代码必须通过当前所有的单元测试(不能引入新的bug)
- 贡献代码必须提供新的单元测试方案
2.2 分支说明
主线分支
当前社区代码主线有:mater 和 branch-X (X是版本,如hive2版本主线是 branch-2)。
master分支主要包含当前开发的新功能和所有的bug修复。branch-X主要用于版本发布。
发布分支和功能分支
发布版本通过branch-X来发布。而功能分支通常是用于开发新功能,当功能开发稳定之后,会合并至master分支。
tips:所以,提交patch必须要注意是哪个版本的bug?如果是hive2.0,你的patch开发代码需要从branch-2分支拉取,确保不会合并主线新的功能到你的patch中。如果你的bug是所有版本都存在的,则可以从master分支拉取(社区committer或PMC会考虑是否合入其他版本分支)。
现在你可以拉取自己的分支,并进行bug修复。完成开发之后,必须进行单元测试。
2.3 修改代码
修改代码需要注意几点:
- 不要格式化修改无关的代码
- 修改的废弃的代码不要注释,而是删除掉
- 修改的周围最好加上标注,说明修改的内容和目的,以便后人理解查看
- 只保留有用的代码,
2.4 单元测试
快速浏览测试步骤:
第一步:在hive工程顶级目录执行编译:
1 mvn clean install -DskipTests第二步:编译itests工程:
1
2 cd itests
mvn clean install -DskipTests -Drat.skip=true第三步:执行测试脚本
1
2 cd qtest
mvn test -Dtest=TestCliDriver -Dqfile=<filename>.q -Dtest.output.overwrite=true
在本地单元测试之前,你需要将当前版本包安装到本地maven仓库:(重要前提条件)
1 | mvn clean install -DskipTests |
Hive支持两种单元测试:一种是Java代码的单元测试;另一种是Sql脚本的单元测试(通常使用后一种单元测试)。
Sql脚本测试分两类:积极的和消极的。对应的测试类分别是TestCliDriver
和 TestNegativeCliDriver
。
tips:测试前,需要确保将当前测试包安装至本地maven仓库中。
Java代码相关测试:
1 | -- 运行独立的单元测试类 |
Sql脚本相关测试:
Sql测试脚本存放目录:
1 | // 测试sql脚本 |
1 | -- 运行所有积极的sql测试 |
远程debug运行单元测试:
1 | mvn -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000 -Xnoagent -Djava.compiler=NONE" test -Dtest=TestCliDriver -Dqfile=<test>.q |
debug代码:
1 | 客户端调试(常用) |
2.5 提交pr(不常用)
Fork一份社区代码,并clone到本地(前面准备工作已完成)
添加一个自己的远程仓库,并指向社区版本库
1 | git remote add jeff_hive https://github.com/apache/hive.git |
设置pr引用(在.git/config文件中,修改如下信息,)
1
2
3
4[remote "jeff_hive"]
url = https://github.com/apache/hive.git
fetch = +refs/heads/*:refs/remotes/jeff_hive/*
fetch = +refs/pull/*/head:refs/remotes/jeff_hive/pr/*修改代码然后提交pr(push request)即可
2.6 提交patch
patch命名规范:
1 | HIVE-<JIRA-NUMBER>[.<patch-num>][.<branch-name>].patch |
本地修改之后,生成patch:
1 | git diff --cached > HIVE-22412.branch-2.path |
生成patch方式二:
1 | <commitid> 是社区分支的最后一次提交;如果拉取分支已经过了很久,一定要确定是否是最新的提交,确保提交的patch是干净的 |
3 感触
在日常开发中,积极参与开源社区动态,会让自己额外具有成就感。
之前有朋友说:我也想贡献社区,但苦于发现不了bug。其实,在工作中往往我们使用的版本都是相对稳定的老版本,即使发现引擎bug,往往在高版本中已经进行了修复。
但我们不能因此就失去了贡献社区的机会,往往在社区JIRA中有很多没有解决的issue,如果感兴趣且工作之余时间充足,可以领取感兴趣的issue尝试修复下。
本文链接: https://stefanxiepj.github.io/archives/5b333215.html
版权声明: 本作品采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。转载请注明出处!
![知识共享许可协议](https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png)