如何贡献

贡献者许可协议 (CLA)

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

  • 如果您是编写原始源代码的个人，并且您确定自己拥有该知识产权，请提交个人 CLA。
  • 如果您为一家公司工作，则必须提交公司 CLA，以表明允许您向此客户端库贡献代码。

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

提交补丁程序概览

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

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

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

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

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

设置开发环境

前提条件

  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"

从 GitHub 向 GitHub 进行身份验证

为了能够从 GitHub 签出代码，您必须使用 HTTP 或 SSH 通过 GitHub 进行身份验证。在继续按照以下说明操作之前，请阅读 GitHub 说明，了解如何开始使用 HTTPS 或 SSH 克隆。如需从总体上详细了解 Git，Pro Git 是一个很好的资源。

检查代码

使用 HTTPS

如需查看开发“分支”分支中的库代码库，请运行以下命令：

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 services。
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/repository）。在从 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 输出中，选中名为“要提交的更改”的部分。

开始代码审核

准备好接受审核后，请在 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 命令应用该差异：
patch -p1 < issue123456.diff

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

测试更改集

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

mvn clean install checkstyle:check

在 codereview.appspot.com 上批准变更集

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

提交代码

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

git pull

如有任何冲突，请先解决，然后确保让所有测试都再次通过。

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

git commit

输入如下消息（假设您要修复或实现问题 # 123，如 GitHub 问题跟踪器中所述）：

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

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

  • 如果这样可以解决问题跟踪器中的问题，请添加问题编号（如下所示）。
  • 如果这是针对特定分支的更改，请包含分支编号。
  • 您将成为此次提交的 committer，但请将更改标记为 author (--author=<author>)，以便注明更改者。

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

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

git push

如果在 git push 期间您会收到有关更新被拒的错误消息（可能是因为您忘记运行 git pull），请按下列步骤与最新更改合并并将更改推送到远程代码库： 

git pull
git commit
git push

解决问题

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

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

取消修补变更集

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

git checkout -- .