捐款方式

捐助計畫授權協議 (CLA)

您必須先提交個人或公司貢獻者授權協議 (CLA)，我們才能接受您的修補程式修補程式：

  • 如果您是撰寫原始原始碼的人員，且自己擁有該智慧財產，請提交個人 CLA。
  • 如果您是公司，貴公司就必須提交企業 CLA，以表明您能夠向這個用戶端程式庫貢獻作品。

請透過上述任一連結存取適當的 CLA，以及如何簽署及傳回 CLA 的操作說明。收到這些資料後，我們就會將您加入官方捐款者名單。

提交修補程式總覽

如要將程式碼提供給這個專案，請按照下列一般步驟操作：

  1. 按照上方說明簽署《貢獻者授權協議》。
  2. 加入我們的討論群組。
  3. 設定開發環境。
  4. 透過 GitHub 的 Issue Tracker，將每個變更集和問題 (錯誤報告或功能要求) 建立關聯。如果尚未建立新問題，請先指派給自己，再指派給自己。
  5. 查看程式碼、前往 codereview.appspot.com 建立新問題，然後完成程式碼審查程序。以下提供所有程序的詳細操作說明。
  6. 審查完程式碼並收到核准後，請修訂程式碼。如果您不是官方的貢獻者，捐助計畫會將您的變更集提取到官方存放區。

我們會使用下列工具和程序：

  • 我們使用 Git 做為版本管控系統。
  • 我們使用 Maven 和建構系統以及二進位發行系統。
  • 我們會使用 codereview.appspot.com 進行程式碼審查。(請注意，在 codereview.appspot.com 工具中，「issue」是指程式碼審查要求，而在 GitHub Issue Tracker 中，「issue」則為功能要求或錯誤報告。

如果您是 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"

透過 GitHub 使用 GitHub 進行驗證

如要從 GitHub 查看程式碼，您必須透過 HTTP 或 SSH 使用 GitHub 進行驗證。在繼續按照下方的操作說明進行之前，請詳閱 GitHub 操作說明，瞭解如何開始使用 HTTPS 或 SSH 複製。如要進一步瞭解 GitHub，Pro Git 是很棒的資源。

查看程式碼

使用 HTTPS

如要查看開發「主要」分支版本中的程式庫存放區，請執行下列指令：

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

使用 SSH

如要查看開發「分支版本」開發分支中的程式庫存放區，請確認您已具備 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 Manager」，或是在指令列中執行 android。
  2. 捲動至套件清單底部，然後選取「Extras > Google Play services」(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 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 工具，以便找出程式碼中的錯誤。如果系統回報任何錯誤，您必須加以修正或更新 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 存放區分支版本，並為此新功能或錯誤修正建立一個分支版本。傳送自己分支的程式碼審查要求時，請確認分支與上游存放區同步。詳情請參閱 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 等名稱，將原始 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 的 Issue Tracker 所示)：

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

第一個冒號和說明前：

  • 如果這項修正在 Issue Tracker 上已修正，請附上問題編號，如圖所示。
  • 如果這是特定分支版本的變更，請加入分支版本編號。
  • 您將成為這個修訂版本的 committer，但請將標記標示為 author (--author=<author>)，藉此將變更內容提供給作者。

按照說明操作，請一律在程式碼審查網站上加入問題的連結。這個連結非常重要，因為在沒有修訂版本的情況下，無法找出與修訂版本相關的程式碼審查，這有助於保留討論記錄。

如要將變更推送至 GitHub 存放區：

git push

如果在 git push 期間，您收到更新遭拒的錯誤訊息 (您可能忘記執行 git pull)，請參閱這篇文章，瞭解如何合併最新變更並將變更推送到遠端存放區：

git pull
git commit
git push

關閉問題

請務必在程式碼審查工具中關閉問題。操作說明如下：

  1. 在 codereview.appspot.com 中選取問題。
  2. 按一下左上方「Id」的「X」

修補變更集

如果您基於某些原因，決定不修訂已匯入的變更集，請使用下列指令將其關閉。注意：實際上是清除所有本機變更，

git checkout -- .