如何貢獻

協作者授權協議 (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 自動處理的 .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 instructions,瞭解如何開始使用 HTTPS 或 SSH 複製功能。如要進一步瞭解 Git 的一般概念,Pro 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

如何切換回主要分支版本:

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-clientgoogle-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 等名稱將原始差異檔案儲存至本機電腦。
  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. 按一下左上角的「X」,前面的「Id」。

取消修補變更集

如果因為某些原因而決定不提交您匯入的變更集,請使用下列指令來刪除。注意:這項功能會清除所有本機變更。

git checkout -- .