如何貢獻

貢獻者授權協議 (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 工具中，「問題」一詞 是指程式碼審查要求；在 GitHub Issue Tracker 中，我們會提供「問題」是 功能要求或錯誤報告)。

如果您是 Eclipse 開發人員，請使用專案專屬的程式碼格式 ，並由 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"

透過 Git 使用 GitHub 進行驗證

要在 GitHub 查看程式碼，您必須使用 您就能使用 HTTP 或 SSH繼續 請參閱下列 GitHub 操作說明 操作說明，瞭解如何取得 開頭為 HTTPS 或 SSH 複製如要進一步瞭解 Git 一般來說，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. 捲動至套件清單底部，然後選取額外項目 >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 工具，找出程式碼中的錯誤。如果發生錯誤 ，您必須修正錯誤或更新 findbugs-排除.xml 檔案。(請注意，FindBugs 的速度很慢)。

mvn findbugs:check

變更內容通過所有測試後，請將變更新增至索引 (Git 暫存器) 區域)：

git add .

仔細檢查您新增、修改或刪除的所有檔案 索引中：

git status

在 git status 輸出內容中，查看「Changes to beCommit」(要修訂的變更) 部分。

開始程式碼審查

準備好進行審查時，請在 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. 將原始 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

如有任何衝突，請解決衝突，確保讓所有測試都能 重返中途

如何修訂程式碼的 locally： 

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. 按一下「X」位於左上角的「Id」前方

取消修補變更集

如果您因為某些原因決定不提交已匯入的變更集，請使用 才能刪除該資料集注意：實際的本機變更會自動清除。 

git checkout -- .