贡献者许可协议 (CLA)
您需要先提交个人或企业贡献者许可协议 (CLA),我们才能接受您的代码补丁:
请按照上述两个链接之一访问相应的 CLA 和说明,了解如何签署和返回 CLA。收到您的回复后,我们便会将您添加到官方贡献者列表。
提交补丁概览
如需为此项目贡献代码,请按照以下常规步骤操作:
- 签署贡献者许可协议(如上所述)。
- 加入我们的论坛。
- 设置开发环境。
- 将您的每个变更集与 GitHub 问题跟踪器中的对应问题(bug 报告或功能请求)相关联。如果还没有问题,请创建新问题,并将其分配给您自己。
- 请签出代码,在 codereview.appspot.com 上创建新问题,然后完成代码审核流程。下面提供了所有这些流程的详细说明。
- 您的代码经过审核并获得批准后,请提交该代码。如果您不是官方贡献者,贡献者会将您的更改集提取到官方代码库中。
我们使用以下工具和流程:
- 我们使用 Git 作为版本控制系统。
- 我们将 Maven 用于构建系统,以及一个二进制分发系统。
- 我们使用 codereview.appspot.com 进行代码审核。(但请注意,在 codereview.appspot.com 工具中,术语“问题”是指代码审核请求,而在 GitHub 问题跟踪器中,“问题”是指功能请求或 bug 报告。)
如果您是 Eclipse 开发者,请使用 Eclipse 自动处理的 .settings 目录中指定的项目特定代码格式。
设置开发环境
前提条件
- 安装 Java 6。您可能需要设置
JAVA_HOME
变量。 - 安装 Maven。(本文档假定您对 Maven 命令有基本的了解。)
- 可选:安装 Android SDK,并将 ANDROID_HOME 变量设置为 Android 的安装位置。
- 安装 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 文件。操作方法如下:
- 启动 Eclipse,然后依次选择 Window > Android SDK Manager,或在命令行中运行
android
。 - 滚动到软件包列表的底部,然后依次选择 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 的所有三个库的新版本时,您必须按以下顺序编译它们:
- google-http-java-client
- google-oauth-java-client
- 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 克隆,请执行以下操作:
- 在 codereview.appspot.com 中打开问题。
- 对于相关补丁,请在补丁规范的右上角查找“下载原始文件”。
- 点击“原始”可获取要导入的文件的网址。
- 将原始 diff 文件保存到本地计算机上,并命名为“issue123456.diff”。
- 转到本地 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
关闭问题
请务必在代码审核工具中关闭问题。操作方法如下:
- 在 codereview.appspot.com 中选择问题。
- 点击左上角的“X”(位于“Id”前面)。
取消修补更改集
如果您出于某种原因决定不提交导入的变更集,请使用以下命令进行移除。请注意:此操作会彻底清除您在本地的所有更改。
git checkout -- .