如何贡献自己的力量

贡献者许可协议 (CLA)

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

  • 如果您是以个人身份编写原始源代码，并且确定 证明您拥有该知识产权，请提交 单独的 CLA。
  • 如果您供职于公司，则贵公司必须提交公司 CLA 以表明您有权向此客户端库贡献自己的代码。

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

提交补丁概览

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

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

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

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

如果您是 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 代码库中 说明 从 HTTPS 或 SSH 克隆开始。如果您想详细了解 Git，请参阅 一般来说，Pro Git 是一个很好的资源。

查看代码

使用 HTTPS

要在开发“master”中签出库代码库，请执行以下操作：分支 运行以下命令：

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

使用 SSH

要在开发“master”中签出库代码库，请执行以下操作：分支、make 没问题 拥有对 GitHub 代码库的写入权限，然后运行以下命令：

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

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

git checkout --track origin/1.12

如需切换回主分支，请运行以下命令：

git checkout master

从 GitHub 代码库拉取最新更改并更新本地 工作树复制到最新的提交内容：

git pull

Maven

安装 Google Play 服务

首次设置项目时，您需要安装 google-play-services.jar 文件中。具体操作步骤如下：

  1. 启动 Eclipse 并选择 Window >Android SDK 管理器，或运行 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/repository）。它会先搜索该代码库中的二进制文件，然后再提取 从 Maven 中央代码库获取。

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

  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 ...

进行更多更改后，暂存新的更改。如需上传新的补丁，请执行以下操作： 则运行以下命令： 

upload.py --rev=HEAD -i 123456

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

如果您更喜欢传统的 GitHub 工作流， 那么您可能已经克隆了 GitHub 代码库，并针对此新功能或问题修复创建了一个分支。当您 发送验证码 审核来自您自己的分支的请求，请确保您的分支与 上游代码库如需了解详情，请参阅 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. 以如下名称将原始差异文件保存到本地计算机： issue123456.diff。
  5. 转到本地 Git 工作树，并使用 patch 应用差异比较 命令：
patch -p1 < issue123456.diff

如需仔细检查是否导入了正确的 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 -- .