如何贡献自己的力量

贡献者许可协议 (CLA)

您需要先提交个人或企业贡献者许可协议 (CLA)，我们才能接受您的代码补丁：

  • 如果您是编写原始源代码的个人，并且确定自己拥有知识产权，请提交单独的 CLA。
  • 如果您供职于某家公司，您的公司必须提交公司 CLA，以表明您允许为此客户端库贡献内容。

请按照上述两个链接之一访问相应的 CLA 和说明，了解如何签署和返回 CLA。收到您的回复后，我们便会将您添加到官方贡献者列表。

提交补丁概览

如需为此项目贡献代码，请按照以下常规步骤操作：

  1. 签署贡献者许可协议（如上所述）。
  2. 加入我们的论坛。
  3. 设置开发环境。
  4. 将您的每个变更集与 GitHub 问题跟踪器中的对应问题（bug 报告或功能请求）相关联。如果还没有问题，请创建新问题，并将其分配给您自己。
  5. 请签出代码，在 codereview.appspot.com 上创建新问题，然后完成代码审核流程。下面提供了所有这些流程的详细说明。
  6. 您的代码经过审核并获得批准后，请提交该代码。如果您不是官方贡献者，贡献者会将您的更改集提取到官方代码库中。

我们使用以下工具和流程：

  • 我们使用 Git 作为版本控制系统。
  • 我们将 Maven 用于构建系统，以及一个二进制分发系统。
  • 我们使用 codereview.appspot.com 进行代码审核。（但请注意，在 codereview.appspot.com 工具中，术语“问题”是指代码审核请求，而在 GitHub 问题跟踪器中，“问题”是指功能请求或 bug 报告。）

如果您是 Eclipse 开发者，请使用 Eclipse 自动处理的 .settings 目录中指定的项目特定代码格式。

设置开发环境

前提条件

  1. 安装 Java 6。您可能需要设置 JAVA_HOME 变量。
  2. 安装 Maven。（本文档假定您对 Maven 命令有基本的了解。）
  3. 可选：安装 Android SDK，并将 ANDROID_HOME 变量设置为 Android 的安装位置。
  4. 安装 Git。

设置 Git

使用 git config 命令设置默认显示名称和电子邮件地址：

git config --global user.name "YOUR NAME"
git config --global user.email "YOUR EMAIL ADDRESS"

通过 Git 向 GitHub 进行身份验证

为了能够从 GitHub 签出代码，您必须使用 HTTP 或 SSH 通过 GitHub 进行身份验证。在继续按照以下说明操作之前，请先阅读 GitHub instructions，了解如何开始使用 HTTPS 或 SSH 克隆。如果您想大致了解 Git，请参阅专业 Git 资源。

检出代码

使用 HTTPS

如需在开发“master”分支中检出库代码库，请运行以下命令：

git clone https://github.com/google/google-api-java-client.git

使用 SSH

要在开发“master”分支中检出库代码库，请确保您拥有 GitHub 代码库的写入权限，然后运行以下命令：

git clone git@github.com:google/google-api-java-client.git

如需切换到替代分支（例如 1.12），请运行以下命令：

git checkout --track origin/1.12

如需切换回 master 分支，请执行以下操作：

git checkout master

如需从 GitHub 代码库提取最新的更改，并将本地工作树更新为最新的提交，请运行以下命令：

git pull

Maven

安装 Google Play 服务

首次设置项目时，您需要安装 google-play-services.jar 文件。操作方法如下：

  1. 启动 Eclipse，然后依次选择 Window > Android SDK Manager，或在命令行中运行 android。
  2. 滚动到软件包列表的底部，然后依次选择 Extras > Google Play 服务。
mvn install:install-file \
           -Dfile=$ANDROID_HOME/extras/google/google_play_services/libproject/google-play-services_lib/libs/google-play-services.jar \
           -DgroupId=com.google.android.google-play-services \
           -DartifactId=google-play-services \
           -Dversion=1 \
           -Dpackaging=jar

编译项目

mvn clean install

Maven 会将已编译的二进制文件安装到本地代码库（例如 ~/.m2/repo）。它会先搜索该代码库中的二进制文件，然后从 Maven 中央代码库中提取二进制文件。

注意：此库依赖于 google-http-java-client 和 google-oauth-java-client。在处理尚未发布到 Maven Central 的所有三个库的新版本时，您必须按以下顺序编译它们：

  1. google-http-java-client
  2. google-oauth-java-client
  3. google-api-java-client 按此顺序进行编译可确保 Maven 选取已编译的二进制文件进行依赖库编译。

代码审核流程

下载 upload.py 脚本

下载 upload.py 脚本，并根据需要将其添加到 PATH。

首次运行 upload.py 时，它会要求您提供应用专用密码：

Email (login for uploading to codereview.appspot.com): your_email_address@yourdomain.com
Password for your_email_address@yourdomain.com:

准备代码以供审核

在将代码送审之前，您必须运行 Clirr 以捕获代码中的向后兼容性问题。如果报告了任何错误，您需要修复这些错误或更新 clirr-ignored-differences.xml 文件。

mvn -q clirr:check

您还必须运行 FindBugs 工具以捕获代码中的 bug。如果报告任何错误，您需要修复这些错误或更新 findbugs-Exclude.xml 文件。（请注意，FindBugs 速度非常慢。）

mvn findbugs:check

您的更改通过所有测试后，将更改添加到索引（Git 暂存区域）中：

git add .

仔细检查您添加、修改或删除的所有文件是否都已反映在索引中：

git status

在 git status 输出中，选中“Changes to be submit”（要提交的更改）部分。

开始代码审核

准备好以供审核后，在 codereview.appspot.com 上创建一个新问题： 

upload.py --rev=HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

做出更多更改后，请暂存新的更改。如需上传新补丁（例如问题编号 123456），请运行以下命令：

upload.py --rev=HEAD -i 123456

如需查看更多选项，请运行 upload.py --help。

如果您更喜欢典型的 GitHub 工作流，那么您可能已经针对 GitHub 代码库创建分支，并针对这项新功能或 bug 修复创建了一个分支。从您自己的分支发送代码审核请求时，请确保您的分支与上游仓库同步。如需了解详情，请参阅有关如何同步分支的 GitHub 帮助。

您还可以将 upload.py 用于本地提交的更改集。

upload.py --rev=upstream/master:HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

代码审核人员

如果您是代码审核人员，请在批准更改集之前导入并测试更改集，然后提交更改集并将其推送到远程代码库。

导入更改集

如需尽早发现错误，请务必将最新更改从远程仓库拉取到工作树中。请确保您的工作树干净且索引为空。

如需从远程仓库拉取和合并最新提交内容，请执行以下操作：

git pull

如需查看工作树和索引中的内容，请执行以下操作：

git status

如需将补丁导入您的本地 Git 克隆，请执行以下操作：

  1. 在 codereview.appspot.com 中打开问题。
  2. 对于相关补丁，请在补丁规范的右上角查找“下载原始文件”。
  3. 点击“原始”可获取要导入的文件的网址。
  4. 将原始 diff 文件保存到本地计算机上，并命名为“issue123456.diff”。
  5. 转到本地 Git 工作树，并使用 patch 命令应用 diff：
patch -p1 < issue123456.diff

如需仔细检查您导入的差异是否正确，请在工作树中执行 git diff。

测试变更集

如需运行测试并安装，请使用以下命令：

mvn clean install checkstyle:check

批准 codereview.appspot.com 上的更改集

通常，在代码审核人员确信代码已准备就绪之前，无法将代码推送到 GitHub 代码库。此时，惯例是回复消息“LGTM”（看起来不错）。

提交代码

重要提示：在提交代码之前，请将最新更改拉取到工作树中，并将工作树更新为 GitHub 代码库中的最新提交：

git pull

如果出现任何冲突，请先予以解决，然后确保再次通过所有测试。

如需在本地提交代码，请执行以下操作： 

git commit

输入如下消息（假设您要修复或实现 GitHub 问题跟踪器中列出的问题 123）：

#123: NullPointerException when passing null to processFoo()
http://codereview.appspot.com/123456/

在第一个冒号和说明之前：

  • 如果这是对问题跟踪器上问题的修复，请按如下所示附上问题编号。
  • 如果该号码是特定分行的更改，则需添加分行号码。
  • 您将成为此提交的 committer，但请将更改的作者标记为 author (--author=<author>)，以注明更改的作者。

在说明之后，请始终附上指向 Codereview 网站上相应问题的链接。此链接非常重要，因为如果没有它，系统将无法方便地找出与提交相关的代码审核，而这对于维护讨论历史记录很有用。

如需将更改推送到 GitHub 代码库，请执行以下操作：

git push

如果您在 git push 期间收到更新遭拒的错误消息（可能您忘记运行 git pull），请按照以下方法与最新更改合并并将更改推送到远程代码库：

git pull
git commit
git push

关闭问题

请务必在代码审核工具中关闭问题。操作方法如下：

  1. 在 codereview.appspot.com 中选择问题。
  2. 点击左上角的“X”（位于“Id”前面）。

取消修补更改集

如果您出于某种原因决定不提交导入的变更集，请使用以下命令进行移除。请注意：此操作会彻底清除您在本地的所有更改。 

git checkout -- .