怎样贡献代码

chenwq

转自Hadooper论坛:http://www.hadooper.cn/dct/page/65789

获得源码

        首先，你需要Hadoop的 源码。 你可以用SVN获得源码，大部分的开发都在”trunk”下。

svn checkout http://svn.apache.org/repos/asf/hadoop/core/trunk/ hadoop-core-trunk

        如果你想针对某个具体的版本编辑，你可以访问网页 http://svn.apache.org/repos/asf/hadoop/core/tags/ ， 在这个网页下，你可以找到你所需要的版本，你还可以通过以下命令核对某个版本：

  svn checkout http://svn.apache.org/repos/asf/hadoop/core/tags/release-X.Y.Z/ hadoop-core-X.Y.Z

        如果你习惯于用Eclipse做开发，在《EclipseEnvironment》 中，有关于如何设置访问SVN的命令。
改进

        在你修改之前，发一封邮件 给hadoop的开发者们，邮件列表为 Hadoop developer mailing list, 或者在Jira发一个关于你所发现的bug的报告。在信件中你要描述你将做的修改，并且要确认你将做的修改不会与其它开发者的开发或是他们对这个项目的计 划发生冲突。让大家知道你的需求可能要花费你一定的时间，在这个过程中，请保持耐心。 在你修改Hadoop的源码或是用你最喜欢的IDE为Hadoop增加一些好的性能时，请注意以下几点：

1、所有的公有类和方法都必须提供javadoc注释
2、不要用这种格式： @author tags.
3、代码应该符合Sun的规范，但有一个例外：每行用两个空格而不是四个空格作为分割.
4、 新有修改应该通过已有的单元测试. • 应该提供新的单元测试来证明以前的代码存在bugs，而新的代码已经解决了这些bugs. Junit是我们的测试框架。
5、你必须实现一个类名以“Test”开头的类，而且这个类继承于junit.framework.TestCase.
6、在该类中定义测试方法，这些方法的名字要以“test”开头。在这些方法中，通过调用JUnit的一套“assert”方法达到测试的效果。这些以 “test”开头的方法会在执行“ant test”时被调用。
7、默认情况下，不要让你的测试写任何文件到“/tmp”目录下。你可以在设置“test.build.data” 系统属性，这样你可以写文件到该系统属性所指的目录下。
8、如果你的测试中要用到HDFS 机群或者 or a MapReduce 机群请分别用org.apache.hadoop.dfs.MiniDFSCluster 和org.apache.hadoop.mapred.MiniMRCluster. TestMiniMRLocalFS 是一个用到MiniMRCluster 的测试程序。
9、将你的类放在这个目录下：src/test . o TestFileSystem.java 和TestMapRed.java 是两个基于MapReduce的 独立的测试例子。
10、TestPath.java 是一个不基于MapReduce的测试例子.
11、你可以用命令“ant test”运行所有的测试。
你也可以用以下的命令运行某个特定的测试： ant -Dtestcase=<class name without package prefix> test (for example ant -Dtestcase=TestFileSystem test)

理解Ant

        Ant是一种Java编译工具，Hadoop就是用Ant编译的。这一节中将详细阐述在Hadoop中是如何使用Ant的。首先，我们先 阅读一篇好的Ant手册。下面的网址里就包含了一个不错Ant手册，但是请注意Hadoop不是按这个手册里描述的方式架构的。我们仅仅是用下面的手册理 解Ant，而不是理解Ant是如何用于Hadoop中的。
比较好的Ant 手册:
1、http://i-proving.ca/space/Technologies/Ant+Tutorial
2、http://ant.apache.org/manual/tutorial-HelloWorldWithAnt.html

产生补丁包

单元测试

        在你打补丁包之前请确认两 点：一是所有的单元测试成功，二是在编绎时没有任何警告提示。

1. cd hadoop-core-trunk

复制代码

1. ant -Djavac.args="-Xlint -Xmaxwarns 1000" clean test tar

复制代码

等待数秒后，你会看到以下提示信息：

BUILD SUCCESSFUL

        如是是上面的提示信息，则表示成功了。如果是下面的提示信息，则失败 了。

BUILD FAILED

        那么请核实所有的错误信息，错误住处在build/test里，在你继 续之前，解决这些错误。

Javadoc

        请确认 javadoc。

1. ant javadoc

复制代码

1. firefox build/docs/api/index.html

复制代码

请确认你所修改的所有公共类的javadoc都是完整的，能提供正确信 息的并且是正确格式的。你的补丁里也不能含有任何关于javadoc警告。

生成补丁包

使用下面的命令来核实你修改过的所有文件：

1. svn stat

复制代码

添加新的文件：

1. svn add src/.../MyNewClass.java
   
2. svn add src/.../TestMyNewClass.java

复制代码

编辑CHANGES.txt 文件，添加关于你所有修改描述，包括你解决的bug数。如果你要描述的某方面（如一个新的特性或是一个增强功能）没有标签，你就创建一个。然后你用这个标签将对这方面的修改添加到changes.txt中去。同样你也需要这个标签来提交你的patch包。

    用下面的命令来创建一个补丁（从Hapdoop的根目录下操作）：

1. svn diff > HADOOP-1234.patch

复制代码

这个会报告所有的你在本地对Hadoop源码所做的修改，并把这些修改 保存到HADOOP-1234.patch 文件中。重读patch文件，来确定它仅仅包含解决一个问题所需要的修改。

请不要：

请不做与解决bug无关的更改代码格式：代码格式 调整应该与提交patch分开
对于无用的注 释：删除它们
在每个改动的地方插入注释，以标 注修改：大家可以用这种方式即指出谁做了哪些修改
对 于最终用户不需要的东西设为公共的。

请做如下的工作：

请保持你编辑的代码的原有风格
对逻辑和功能不容易被理解的地方添加注释
更新文档 (例如., package.html files, this wiki, etc.)
如果你要更改你补丁中文件的 名字：

写一个脚本，用“svn mv”来重命名以前的文件
编辑需要更改的文件 (例如：更改包的名字).
用'svn diff --no-diff-deleted --notice-ancestry'创建一个补丁文件
提交shell脚本和补丁文件
        这样其它的开发者就能能过运行脚本和打补丁浏览 到你的更改。

测试你的补丁

        在你提交补丁前，建议你 最好用automated Hudson patch 测试系统来测试你的补丁。这样做可以在你提交补丁之前发现并解决里面存在的问题。test-patch Ant target 会像Hudson现在做的工作一样检查你的补丁。 为使用这一功能，你必须保证你是在一个“clean workspace”下运行。(也就是使用 svn stat 命令显示没有修改或是添加)。在这种环境下，运行惟下命令：

ant \
  -Dpatch.file=/patch/to/my.patch \
  -Dforrest.home=/path/to/forrest/ \
  -Dfindbugs.home=/path/to/findbugs \
  -Dscratch.dir=/path/to/a/temp/dir \ (optional)
  -Dsvn.cmd=/path/to/subversion/bin/svn \ (optional)
  -Dgrep.cmd=/path/to/grep \ (optional)
  -Dpatch.cmd=/path/to/patch \ (optional)
  test-patch

        最后，你会从你的控制台上得到一些信息。这些信息就像是由 Hudson的补丁自动测试系统添加到Jira上的注释。临时目录（默认的路径是${user.home}/tmp）会包含一些输出文件。这些地文件会帮 助其它开发者了解这个补丁解决的问题。

注意事项:
默认情况下，“cmd”命令会包含在你的“PATH”环境变量里。
“grep” 命令必须支持“-o”参数(GNU 操作系统里的该命令支持)
“patch”命令必须支 持“-E”参数
你需要设置ANT_HOME。通过命令“ant -diagnostics”你可以知道你系统中默认的ANT。
打补丁

        用下面的命令你可以打一 个补丁，这个补丁可以是你自己生成的，也可以是从JIRA上下载的。

patch -p0 < cool_patch.patch


        如果你只是想试下能否正确打补丁，你可以使用下面的命令：

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

        如果你使用Eclipse，你可以下面的步骤打补丁：1. 右击工程名, 2. 选择Team -> Apply Patch

提交你的工作

        最后，在Jira上创建 关于这个补丁包的问题报告，然后把补丁作为附件上传到Jira上。请添加代码的评语，这个评语是根据我们的code review checklist而产生的。请注意，附件必须包含在ASF里，并且得到一个ASF的许可证(就像 Apache License §5)。 当你认为你的补丁可以提交时，选择Jira上的“Submit Patch”链接提交。提交的补丁会自动地被“ Hudson”测 试。在测试结束时，Hudson会添加一个成功（“+1”）或失败（“-1”）的标志到你Jira上的问题报告里。如果你的问题域里包含多个补丁的版 本，Hudson会测试最新的上传的补丁。

        大家在提交补丁前应该运行 ant clean test javadoc checkstyle。应该通过所有的测试。Javadoc应该没有警告和错误信息。格式检查方面的错误不应该超过 Checkstyle Errors所列的错误。Hudson的测试是一种双重测试，因此不建议用作首要的测试工具，否则它会生成太多的无用信息到Jira和邮件内容 中。但是如果没有通过Hudson测试，而去提交补丁，这是不允许的，除非失败的原因与补丁无关。

        如果你的补丁对整个系统有提高，那么这些提高会通过基准测试程序证实出来。

        如果你的新开发的补丁与最新的核心包有冲突，那么你必须在Jira上设置不相容修改的标志并且在Release Note里作相关记录，包括这两点：一是解释不相容性的影响，二是用户需要做的操作。

       如果你的补丁实现了一个重要的功能或者是重要的改进，那么你必须在Jira上的Release Note里记录这些，使得最终用户能够理解。 如果补丁通过自动补丁测试（即得到一个“+1”的评语）并且代码浏览者已经在Jira问题部分设置了“Reviewed”的标志，那么提交者评估这个代码 数天后可以提交这段代码或者是放弃它并给予一个解释。

        请保持耐心。代码提交者们 都很忙。如果在数天后，仍然没有人对你的补丁给予任何回复，请给予一些友好的提示。如果你觉得其它人的建议是合理的，也请你把这些建议加入到你的补丁中。 最后，请注意一点：即使你的补丁没有被提交，它仍然有用的。

        如果你的Hudson测试 收到一个“-1”的结果，在Jira问题块选择Resume Progress, 修改这个补丁包后重新上传，然后重新选择Submit Patch链接

        提交者：对于不同寻常的改变，最好是在提交之前再找一个提交者来看你的补丁。 像其它贡献者一样使用Submit Patch链接，然后等待第二个提交者的“+1”结果，最后才提交。也请您经常查看在补丁队列中的东西。

Jira 指导方针

        请在Jira中添加评 语，使他们关心的人知道。也请解决Jira上属于你的问题。

        如果可能，请不要编辑描述 性语句和评语。也请不要编辑垃圾邮件列表或者整理Jira上的“All”，这些东西可能会很有用。相反，如果浏览描述和评语请用浏览按钮。保持描述的简 洁，并保存更多的可能的详细的评语。如果你改变想法，将新的想法用一个新的评语记下来而不是编辑旧的评语。这个问题需要保存历史以便以后的讨论。

保持联系

        贡献者们应该加入到 Hadoop的邮件列表中（Hadoop mailing lists）.特别地，提交列表：是查看代码改变的; 发展列表（dev list）:参与讨论关于所有的改变; 用户列表：帮助其它人

参考：

Apache contributor documentation
Apache voting documentation