如何为 Apache Hive 贡献力量

本页描述了如何为 Apache Hive 贡献软件的机制。有关您可能会做什么的想法，请参阅Jira中的待售票。

获取源代码

首先，您需要 Hive 源代码。

使用 git 获取本地驱动器上的源代码。请参阅下面的HowToContribute#了解 Hive 分支，以了解您应该使用哪个分支。

git clone https://github.com/apache/hive

设置 Eclipse 开发环境(可选)

这是一个可选步骤。 Eclipse 具有许多 Java 开发的高级功能，并且使 Hive 开发人员的工作变得更加轻松。

如何导入 eclipse？

成为贡献者

此清单告诉您如何创建帐户并获得 Hive 贡献者所需的权限。有关其他信息，请参见Hive website。

• 如果您还没有以下帐户，请创建一个 Apache Software Foundation JIRA 帐户：注册 JIRA。

• ASF JIRA 系统仪表板为here。

  • Hive JIRA 是here。

• 要查看 JIRA 票证的补丁，请使用Review Board。如果您需要一个帐户，register here。有关更多信息，请参见下面的HowToContribute#Review Process。

• 张贴供审查的所有 Hive 修补程序都在here中列出。

  • 提出审阅请求后，单个 JIRA 票证会在审阅板上提供指向该问题的链接。

  • 对于简单的 Comment，您只需阅读 JIRA 票证附带的补丁并发表 Comment 即可。

• 要贡献给 Hive Wiki，请遵循关于本维基中的指示。

• 要编辑 Hive 网站，请按照如何编辑网站中的说明进行操作。

• 加入Hive 邮件列表以接收有关问题和讨论的电子邮件。

Making Changes

在开始之前，请向Hive 开发人员邮件列表发送消息，或在JIRA提交错误报告。描述您建议的更改，并检查它们是否适合其他人正在做的事情以及为该项目计划的事情。请耐心 await，可能需要一些时间来了解您的要求。

使用您喜欢的 IDE 修改源代码并添加一些功能。

Coding Conventions

请注意以下几点。

• 所有公共类和方法都应提供内容丰富的Javadoc comments。

• 不要使用@author 标签。

• 代码应按照Sun's conventions格式化，但有两个 exception：

• 每级缩进两(2)个空格，而不是四(4)个空格。

  • 行长度限制为 120 个字符，而不是 80 个字符。

dev-support 文件夹中提供了一个 Eclipse formatter-可以与 Eclipse 和 Intellij 一起使用。请在编辑源代码之前考虑将其导入。

• • For Eclipse:

• 转到首选项-> Java->代码样式->格式化程序；导入 eclipse-styles.xml;应用。

  • 另外更新保存操作：Java->编辑器->保存操作；检查以下内容：保存时执行以下操作；格式化源代码；格式化编辑的行。

  • For Intellij:

• 转到设置->编辑器->代码样式-> Java->方案；点击 Management；导入 eclipse-styles.xml;应用。

• 贡献不应引入新的 Checkstyle 违规。

• 通过运行mvn checkstyle:checkstyle-aggregate来检查是否有新的Checkstyle违规，然后在target/site目录中检查结果。如果在模块的根目录中发出了mvn命令，则可以对特定模块运行检查。

  • 如果使用 Eclipse，则应安装eclipse-cs Checkstyle 插件。该插件突出显示代码中的违规行为，并且还能够自动更正某些类型的违规行为。

• 贡献应该通过现有的单元测试。

• 应该提供新的单元测试来演示错误和修复。 JUnit是我们的测试框架：

• 您应该为 junit4 创建测试类，其类名必须以“ Test”前缀开头。

  • 您可以使用命令mvn test运行所有单元测试，也可以使用命令mvn test -Dtest=<class name without package prefix>运行特定的单元测试(例如：mvn test -Dtest=TestFileSystem)。

  • 上载补丁程序之后，可能值得检查一下是否在预提交作业中执行了新测试。

Understanding Maven

Hive 是一个“多模块” Maven 项目。如果您是Maven的新手，那么以下文章可能会引起您的兴趣：

• 五分钟行家

• Maven 入门

• Maven 示例-多模块项目

另外，Hive 实际上有两个项目，“核心”和“项目”。未将 itest 连接到堆芯反应堆的原因是 itest 需要构建包装。

您需要的实际 Maven 命令在HiveDeveloperFAQ页上进行了讨论。

了解配置单元分支

Hive 有一些“主线”，即 master 和 branch-X。

Hive 中的所有新功能工作和错误修复均归功于 master 分支。发行是从分支 X 完成的。主要版本(例如 2.x 版本)不一定与 1.x 版本向后兼容。向后兼容将在 branch-1 上接受。

除这些主线外，Hive 还具有两种类型的分支，即发布分支和功能分支。

社区准备 Hive 发行版时，发行分支由 Branch-1(对于 1.x)或 master(对于 2.x)组成。发行分支与发行版本号匹配(例如，Hive 1.2 的分支 1.2)。对于补丁程序发行版，该分支由现有发行版分支组成(以避免从主线获得新功能)。例如，如果要发布 1.2.1 版本，则将从分支 1.2 的尖端创建分支 1.2.1. 创建发行分支后，发行 Manager 可以自行决定是否在该分支上包含其他补丁。从分支发布一个版本后，仍然可以在下一补丁版本发布之前对该分支应用其他错误修复。应用于发行分支的所有错误修复都必须首先应用于 master(如果适用，也可以应用于 branch-1)。

功能分支用于开发新功能，而不会破坏其余的 Hive。功能分支的目的是一旦功能稳定后将其合并回 master。

有关 Hive 分支的一般信息，请参见Hive 版本和分支。

Hadoop Dependencies

Hadoop 依赖项在 master 和 branch-1 中的处理方式不同。

branch-1

在 branch-1 中，同时支持 Hadoop 1.x 和 2.x。 Hive 版本通过 Maven 下载了许多不同的 Hadoop 版本，以便编译允许与这些 Hadoop 版本兼容的“填充”。但是，其余的 Hive 仅针对单个 Hadoop 版本构建和测试。

Maven 构建具有两个配置文件，用于 Hadoop 1.x 的hadoop-1和用于 Hadoop 2.x 的hadoop-2。在构建时，必须通过 Maven 的-P命令行选项(请参见如何构建所有来源)指定要使用的配置文件。

branch-2

Hive 的 master 分支不再支持 Hadoop1.x。无需为大多数 Maven 命令指定配置文件，因为将始终选择 Hadoop2.x。

Unit Tests

提交补丁程序时，强烈建议您在本地执行测试，相信除了所有新测试之外，这些测试都会受到影响。完整的测试套件可以由Hive PreCommit 补丁测试执行。 Hive 开发人员常见问题解答描述了如何执行一组特定的测试。

mvn clean install -DskipTests
mvn test -Dtest=SomeTest

即使在非常快的机器上，单元测试也要花费很长时间(几个小时)才能 Sequences 运行。

添加单元测试

可以添加两种单元测试：用于测试 Hive 整个组件的单元测试，以及用于运行查询以测试功能的单元测试。

Java 单元测试

要测试 Hive 的特定组件，请执行以下操作：

• 在组件的*/src/test/java目录中添加一个新类(名称必须以Test开头)。

• 要仅测试新的测试用例，请运行mvn test -Dtest=TestAbc(其中TestAbc是新类的名称)，它将比测试所有测试用例的mvn test快。

查询单元测试

如果可以在命令行中使用 Hive 查询测试新功能，则只需添加一个新的*.q文件和一个新的*.q.out文件。

如果功能以ql(查询语言)添加：

• 在ql/src/test/queries/clientpositive中添加一个新的XXXXXX.q文件。 (可选地，为预期在ql/src/test/queries/clientnegative中失败的查询添加新的XXXXXX.q文件.)

• 运行mvn test -Dtest=TestCliDriver -Dqfile=XXXXXX.q -Dtest.output.overwrite=true。这将在ql/src/test/results/clientpositive中生成一个新的XXXXXX.q.out文件。

• 如果要在测试运行中运行多个.q 文件，则可以指定逗号分隔的.q 文件，例如-Dqfile="X1.q,X2.q"。您还可以指定 Java 正则表达式，例如-Dqfile_regex='join.*'。 (请注意，它使用 Java regex，即'join.*'而不是'join*'.)regex 匹配首先在文件名中删除.q，然后再匹配 regex，因此指定join*.q将不起作用。

如果功能已添加到contrib：

• 执行上述步骤，将ql替换为contrib，并将TestCliDriver替换为TestContribCliDriver。

有关更多详细信息，请参见常见问题解答“ 如何添加测试用例？”。

Beeline 查询单元测试

旧版查询测试驱动程序(除 TestBeeLineDriver 以外的所有驱动程序)都使用 HiveCli 运行测试。 TestBeeLineDriver 使用Beeline client运行测试。为它们创建一个特定的数据库，以便测试可以并行运行。运行测试，您具有以下配置选项：

• -Dqfile=XXXXXX.q-运行一个或多个特定查询文件测试。有关确切的格式，请检查“查询单元测试”段落。如果未提供，则仅运行ql/src/test/queries/clientpositive目录中的查询文件，这些查询文件在beeline.positive.include参数的itests/src/test/resources/testconfiguration.properties中提到。

• -Dtest.output.overwrite=true-这将重写ql/src/test/results/clientpositive/beeline中 q.out 文件的输出。默认值为 false，它将根据黄金文件检查当前输出

• -Dtest.beeline.compare.portable-如果此参数为 true，则在比较它们之前将对生成的查询文件和黄金查询输出文件进行过滤。这样，可以使用相同的黄金输出文件针对不同的配置运行现有查询测试。以下命令的结果将从输出文件中过滤掉：EXPLAIN，DESCRIBE，DESCRIBE EXTENDED，DESCRIBE FORMATED，SHOW TABLES，SHOW FORMATED INDEXES 和 SHOW DATABASES。
  默认值为false。

• -Djunit.parallel.threads=1-运行测试的并行线程数。默认值为1。并行化导致一些片状现象

• -Djunit.parallel.timeout=10-在指定的超时后测试将终止。该参数以分钟为单位设置，默认为 10 分钟。 (截至HIVE 3.0.0。)

• BeeLine 测试可以针对现有集群运行。或者，如果未提供，则针对测试期间创建的 MiniHS2 集群。

• -Dtest.beeline.url-应该用于连接到现有集群的 jdbc URL。如果未设置，则将创建一个 MiniHS2 集群。

  • -Dtest.beeline.user-应该用于连接集群的用户。如果未设置，将使用"user"。

  • -Dtest.beeline.password-用于连接集群的密码。如果未设置，将使用"password"。

  • -Dtest.data.dir-集群上的测试数据目录。如果未设置，将使用<HIVEROOT>/data/files。

  • -Dtest.results.dir-要比较的测试结果目录。如果未设置，将使用默认配置。

  • -Dtest.init.script-测试初始化脚本。如果未设置，将使用默认配置。

  • -Dtest.beeline.shared.database-如果为 true，则将使用默认数据库，否则将为每次运行创建特定于测试的数据库。默认值为 false。

Debugging

请参阅《开发指南》中的调试 Hive 代码。

提交公关

关于如何为 github 项目提交 pullrequest，有很多很棒的 howtos。以下是一种解决方法：

用 2 个遥控器设置一个仓库我建议使用 github 用户作为远程名称-如果您还需要添加其他人的存储库，这可能会使事情变得更容易。

# clone the apache/hive repo from github
git clone --origin apache https://github.com/apache/hive
cd hive
# add your own fork as a remote
git remote add GITHUB_USER [email protected]:GITHUB_USER/hive

您将需要一个单独的分支来进行更改。您需要为每项公关活动做到这一点。

# fetch all changes - so you will create your feature branch on top of the current master
git fetch --all
# create a feature branch This branch name can be anything - including the ticket id may help later on identifying the branch.
git branch HIVE-9999-something apache/master
git checkout HIVE-9999-something
# push your feature branch to your github fork - and set that branch as upstream to this branch
git push GITHUB_USER -u HEAD

做出改变

# make your changes; you should include the ticketid + message in the first commit message
git commit -m 'HIVE-9999: Something' -a
# a simple push will deliver your changes to the github branch
git push

如果您认为自己的更改已准备好进行测试和审查，则可以在https://github.com/apache/hive页上打开 PR 请求。

如果您需要进行更改，则只需将进一步的更改推送到分支-但是请记住，任何新的提交都会触发新的测试运行。而且执行测试所需的时间以小时为单位-因此，在进行更改时请记住这一点。

创建补丁

在对本地存储库进行了更改或一组更改之后，您需要创建一个补丁以发布在 JIRA 上。修补程序的命名约定为：

HIVE-<JIRA-NUMBER>[.<patch-num>][.<branch-name>].patch

*<patch-num> *仅在不是第一个补丁程序时才需要。

*<branch-name> *仅在不是主服务器时才需要。 (请参见上面的HowToContribute#了解 Hive 分支。)

因此，打算应用于母版的 JIRA HIVE-9999 的第一个补丁将被命名为“ HIVE-9999.patch”。

同一 JIRA 的第二个补丁将被命名为“ HIVE-9999.2.patch”。

打算将其应用于 branch-1 分支的同一 JIRA 的补丁将命名为HIVE-9999.branch-1.patch“。

以下 git 命令创建一个补丁：

git diff --no-prefix <commit> > HIVE-1234.1.patch

*<commit> *是 Hive(不是您)在提交之前的最后一次提交。请注意，如果从 Hive 存储库中提取或提取信息已有一段时间，则可能需要重新进行基础设置才能使提交最重要，从而创建可以干净地应用的补丁。

请不要：

• 重新格式化与错误无关的代码：格式更改应为单独的补丁/提交；

• Comments 掉现在已过时的代码：只需将其删除；

• 在每个更改周围插入 Comment，标记更改：人们可以使用 git 找出更改内容以及更改对象。

• 公开最终用户不需要的东西。

Please do:

• 尝试遵守您编辑的文件的编码样式；

• 功能或原理不明显的 Comments 代码；

• 添加一个或多个单元测试(请参见上面的HowToContribute#添加单元测试)；

• 更新文档(例如包含* package.html *文件的 Javadocs 和此 Wiki)。

Hive 质量检查人员预先提交测试

如果补丁程序的名称符合above所示的命名约定，则自动化测试系统将运行预提交测试，并将结果作为 Hive QA 的 JIRAComments 发布。根据是否成功执行了所有测试，以及最近是否修改了现有测试或补丁中是否包含新测试以覆盖代码更改，结果给出建议 1 或-1 票(成功或错误)。有关示例，请参见HIVE-9534和HIVE-11752上的 Hive 质量检查 Comments。请注意，有时测试由于与补丁程序无关的原因而失败。

名称不一致的修补程序将被 Hive 质量检查忽略。< *patch-num> *中可以使用一个前导零，例如“ HIVE-9999.02.patch”，但不接受多个前导零(请参见HIVE-12981上的comments)。

要重新测试补丁，您可以取消并重新提交。对于具有不同文件名的新修补程序，这两个状态更改不是必需的，但是如果文件名保持不变，则 Hive QA 会在首次测试后忽略该修补程序，除非您取消并重新提交。

为了防止进行预提交测试，请在 JIRA 问题的“描述”部分中包含区分大小写的短语 NO PRECOMMIT TESTS。您可以稍后根据需要将其删除。有关示例，请参见HIVE-5289，HIVE-7343和HIVE-7375。

附加和提交补丁

本节仅提供附加和提交补丁的基本过程。有关更多信息，请参见下面的HowToContribute#贡献您的工作。

• 将补丁文件附加到 JIRA 票证上：在票证的“更多”选项卡中，选择“附加文件”，然后使用“选择文件”上载文件，然后添加描述性 Comments。

• 将补丁放入审核队列：单击“提交补丁”按钮。按钮名称将更改为“取消补丁程序”，并且票证状态将更改为“可用补丁程序”。

更新补丁

对于补丁更新，我们的惯例是将它们编号为 HIVE-1856.1.patch，HIVE-1856.2.patch 等。然后，在上载新补丁时，再次单击“提交补丁”按钮；这样可以确保它重新进入审核队列。

申请补丁

要应用从 JIRA 生成或找到的补丁，可以发出：

patch -p0 < cool_patch.patch

如果您更喜欢使用 git 来应用补丁，下面的补丁将在树上进行补丁并在其上运行 git add(这非常有用，因为它不会丢失添加/重命名的文件;并且还使 git 能够监督冲突...因此 git mergetool 可用于解决冲突)

git apply -3 -p0 HIVE-1111.1.patch

如果只想检查补丁是否适用，可以使用--dry-run 选项运行补丁：

patch -p0 --dry-run < cool_patch.patch

如果您是 Eclipse 用户，则可以通过以下方法应用补丁：

• 在程序包资源 Management 器中右键单击项目名称。

• 团队->应用补丁。

Review Process

有关说明，请参见Review Board。

• 进行审核时，请使用 Hadoop 的代码审查清单作为粗略指南。

• 在 JIRA 中，使用“提交补丁”将您的审核请求放入队列。

• 如果提交者请求更改，请将发布状态设置为“恢复进度”，然后在准备好后，提交包含必要修补程序的更新补丁，然后再次请求“提交补丁”进行另一轮审核。

• 一旦您的补丁被接受，请确保上载最终版本以授予 ASF 权利。

贡献您的工作

最后，应该通过问题 JIRA 上的“附加文件”链接将补丁“附加”到JIRA中的问题报告中。请添加 Comment，要求进行代码审查。请注意，应将附件授予 ASF 许可，以包含在 ASF 作品中(根据Apache License)。

如果您认为已准备好提交补丁，请选择问题的 JIRA 上的“提交补丁”链接。如果文件是根据命名标准命名的，则单元测试将自动运行。参见Hive PreCommit 补丁测试。测试应该全部通过。如果您的补丁涉及性能优化，则应通过证明有改进的基准进行验证。

如果您的补丁程序与最新的主要版本不兼容，那么您必须在问题的 JIRA 上设置“不兼容更改”标志，并在“发行说明”字段中填写并说明不兼容的影响以及用户必须采取的必要步骤。

如果您的补丁实现了一项主要功能或改进，那么您必须在问题的 JIRA 的“发行说明”字段中填写最终用户可以理解的功能说明。

“发行说明”字段还可以在包含在 Wiki 文档中之前记录用户界面中的更改(例如新的 HiveQL 语法或配置参数)。

提交者应在几天内评估补丁，然后采取以下两种方法之一：提交；或拒绝解释。

请耐心 await。通勤者也很忙。如果几天后没有人响应您的补丁，请进行友好提醒。如果您认为其他建议合理，请将其纳入您的补丁中。最后，请记住，即使未提交的补丁对社区也很有用。

如果您的补丁程序收到“ -1”，请在问题的 JIRA 上选择“continue 进度”，上传包含必要补丁程序的新补丁程序，然后再次选择“提交补丁程序”链接。

提交者：对于不重要的更改，最好让另一个提交者在提交之前检查补丁。像其他贡献者一样，使用 Submit Patch 链接，然后在提交之前 await 另一个提交者的“ 1”。也请尝试经常检查补丁队列中的内容。

JIRA Guidelines

如果您还没有 JIRA 帐户，请注册 JIRA。

请对JIRA中的问题发表 Comment，以表达您的疑虑。也请对您优先考虑的问题投赞成票。

如果可能，请不要编辑描述和 Comments，因为编辑垃圾邮件列表和 JIRA 的“全部”显示会很混乱，否则这将非常有用。而是在发布之前使用预览按钮(Comment 框下方的图标)预览描述和 Comment。

由于 JIRA 的自动发送消息中包含描述，因此请保持简短的描述并保存更详尽的 Comment 建议。如果您改变主意，请在新 Comments 中记录此内容，而不是编辑旧 Comments。问题应保留讨论的历史。

要打开 JIRA 问题，请单击Hive 摘要页面或任何 Hive JIRA 问题顶行上的“创建”按钮。

请在创建问题时将“修订版本”留为空白–在问题关闭之前，不应对其进行标记，然后由提交者关闭它进行标记，以指示该修订版本最早的版本。可以使用“目标版本”来请求新发行的修补程序应使用的版本，而不是“修订版本”。 (目标版本已于 2015 年 11 月添加到“创建问题”表单中.您可以使用左上角的“编辑”按钮将目标版本添加到之前创建的问题中.)

如果不确定如何填写“创建问题”表单，请查看对其他问题所做的工作。以下是几个 Hive JIRA 问题，您可以作为示例使用：

• 错误：HIVE-8485，HIVE-8600，HIVE-9438，HIVE-11174

• 新功能：HIVE-6806, HIVE-7088 , HIVE-11103

• 改进：HIVE-7685，HIVE-9858 , HIVE-10165

• 测试：HIVE-8601，HIVE-10637

• 希望：HIVE-4563，HIVE-10427

• 任务：HIVE-7111，HIVE-7789

issues panel的“最近添加”列表中提供了许多未提交问题的示例。

生成节俭代码

Hive 代码的某些部分由Thrift生成。对于大多数 Hive 更改，您无需担心，但是，如果您修改了任何 Thrift IDL 文件(例如metastore/if/hive_metastore.thrift和service/if/hive_service.thrift)，那么您还需要重新生成这些文件并将其更新版本作为您的补丁。

以下是与hive_metastore.thrift相关的步骤：

• 除非按照以下说明进行操作，否则请勿对hive_metastore.thrift进行任何更改。

• 使用批准的 Thrift 版本。当前是thrift-0.9.3，您可以从http://thrift.apache.org/获取。 (或在 Mac 上：brew install [email protected]，无需构建，请跳至步骤 4.)

• 从源代码构建 Thrift 编译器，然后安装它：

• cd /path/to/thrift-0.9.3

  • ./configure --without-csharp --without-ruby

  • make

  • sudo make install

• 在 continue 之前，请验证which thrift返回刚刚安装的 Thrift 的内部版本(在 Linux 上通常为/usr/local/bin)；如果不是，请编辑您的 PATH 并重复验证。还要验证命令“ thrift -version”是否返回了所需的 Thrift 版本号。

• 现在，您可以运行 Maven 的“ thriftif”配置文件来生成 Thrift 代码：

• cd /path/to/hive-trunk/

mvn clean install -Pthriftif -DskipTests -Dthrift.home=/usr/local -Phadoop-2

• 如果看到关于找不到 fb303.thrift 的错误，请将其复制到相应的目录中，然后再次运行上述命令。

• On centOS/RHEL:
  cp /path/to/thrift-0.9.3/contrib/fb303/if/fb303.thrift /usr/local/share/fb303/if/fb303.thrift

• 在使用自制软件的 Mac 上：
  $ cd /usr/local/Cellar/[email protected]/0.9.3 && mkdir -p share/fb303/if && cd share/fb303/if && curl -o fb303.thrift https://raw.githubusercontent.com/apache/thrift/master/contrib/fb303/if/fb303.thrift

• 验证代码生成是无操作的，如果您具有正确的 Thrift 版本并且每个人都在遵循这些说明，则应该是这种情况。您可以使用git status或svn status。如果您无法找出问题所在，请向提交者寻求帮助。

• 现在，对hive_metastore.thrift进行更改，然后从/ path/to/hive-trunk /<hive_metastore.thrift's module>再次运行编译器：

mvn clean install -Pthriftif -DskipTests -Dthrift.home=/usr/local -Phadoop-2

• 现在使用svn status和svn diff或git status and git diff来验证重新生成的代码仅与您对hive_metastore.thrift所做的更改相对应。如果生成了新文件，则可能还需要svn add或git add(如果已废弃了文件，则可能需要svn remove或git rm)。

• cd /path/to/hive-trunk

• ant clean package

• 验证 Hive 在嵌入式和远程元存储配置中仍然可以正常工作。

Stay Involved

贡献者应加入Hive 邮件列表。特别是开发人员列表(以加入有关更改的讨论)和用户列表(以帮助其他人)。

See Also

• Apache 贡献者文档

• Apache 投票文档

• 如何编辑网站