コントリビューターとしての活動

コントリビューター ライセンス契約（CLA）

コードパッチの受理前に、個人または法人のコントリビューター ライセンス契約（CLA）を提出する必要があります。

  • オリジナル ソースコードを記述している個人で、知的財産権を所有していると確信できる場合は、個別の CLA を提出してください。
  • 企業に勤務している場合は、法人の CLA を提出して、このクライアント ライブラリへの作品提供が認められていることを示す必要があります。

上記のいずれかのリンクをクリックして該当する CLA を取得し、署名と返信の方法を確認してください。確認が取れ次第、正式な協力者リストに追加いたします。

パッチの送信の概要

このプロジェクトにコードを投稿する手順は次のとおりです。

  1. 上記のようにコントリビューター ライセンス契約に署名します。
  2. ヘルプ グループにご参加ください。
  3. 開発環境を設定します。
  4. GitHub Issue Tracker で、各変更セットを問題（バグレポートまたは機能リクエスト）に関連付けます。新しい問題がまだない場合は作成し、自分に割り当てます。
  5. コードをチェックアウトし、codereview.appspot.com で新しい問題を作成し、コードレビュー プロセスを完了する。これらのプロセスの詳細な手順を以下に示します。
  6. コードがレビューされ、承認を受けたら、コードを commit します。正式なコントリビューターでない場合、コントリビューターが変更セットを公式リポジトリに pull します。

Google では以下のツールとプロセスを使用しています。

  • バージョン管理システムとして Git を使用しています。
  • Maven をビルドシステムとバイナリ配信システムに使用します。
  • コードレビューには codereview.appspot.com を使用しています。（ただし、codereview.appspot.com ツールでは、「問題」はコードレビュー リクエストを意味するのに対し、GitHub Issue Tracker では、「問題」は機能リクエストまたはバグレポートであることに注意してください。）

Eclipse 開発者は、.settings ディレクトリで指定されているプロジェクト固有のコード形式を使用します。このコード形式は 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 のクローン作成を開始する方法について、GitHub のinstructionsをお読みください。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

master ブランチに戻すには、次のコマンドを実行します。

git checkout master

GitHub リポジトリから最新の変更を pull し、ローカル作業ツリーを最新の commit に更新します。

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 セントラルにまだリリースされていない 3 つのライブラリの新しいバージョンを利用する場合は、次の順序でコンパイルする必要があります。

  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 の出力で、「Changes to be commit」というセクションを確認します。

コードレビューの開始

レビューの準備ができたら、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 のヘルプをご覧ください。

ローカルで commit された変更セットにも upload.py を使用できます。

upload.py --rev=upstream/master:HEAD --base_url=https://github.com/google/google-api-java-client --send_mail -r reviewer@somedomain --cc ...

コードレビュー担当者

コードレビュー担当者の場合、変更セットを承認する前にインポートとテストを行い、変更セットをリモート リポジトリに commit して push します。

変更セットのインポート

エラーを早期に発見するには、リモート リポジトリから最新の変更を作業ツリーに pull します。作業ツリーがクリーンで、インデックスが空であることを確認します。

リモート リポジトリから最新の commit を pull して統合するには:

git pull

作業ツリーとインデックスの内容を確認するには:

git status

ローカル Git クローンにパッチをインポートするには:

  1. codereview.appspot.com 内で問題を開く。
  2. 対象のパッチの場合、パッチ仕様の右上にある [Download raw] を確認します。
  3. [raw] をクリックして、インポートするファイルの URL を取得します。
  4. 未加工の差分ファイルを issue123456.diff のような名前でローカルマシンに保存します。
  5. ローカル Git 作業ツリーに移動し、patch コマンドを使用して差分を適用します。
patch -p1 < issue123456.diff

正しい差分がインポートされたことを再確認するには、作業ツリーで git diff を実行します。

変更セットをテストする

テストを実行してインストールするには、次のコマンドを使用します。

mvn clean install checkstyle:check

codereview.appspot.com の変更セットの承認

一般に、コードの準備ができたら、コード審査担当者によって判断されるまで、コードを GitHub リポジトリに push できません。その時点で「LGTM」（Looks Good To Me）というメッセージで返信するのが慣例となっています。

コードの commit

重要: コードを commit する前に、最新の変更を作業ツリーに pull して、GitHub リポジトリにある最新の commit に作業ツリーを更新してください。

git pull

競合がある場合は解決し、すべてのテストに合格するようにします。

コードをローカルに commit するには: 

git commit

次のようなメッセージを入力します（GitHub Issue Tracker に表示されている問題 # 123 を修正または実装している場合）。

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

最初のコロンと説明の前:

  • これが Issue Tracker の問題に対する修正である場合は、表示されている問題番号を記載します。
  • もしこれが特定のブランチに関する変更である場合は、そのブランチ番号も記載してください。
  • あなたはこのコミットの committer になりますが、変更の作成者を author（--author=<author>）としてマークしてクレジットを表示してください。

説明の後、コードレビュー サイトに問題へのリンクを必ず記載します。このリンクがないと、commit に関連するコードレビューを把握する便利な方法が得られず、ディスカッションの履歴を維持できるため、このリンクは重要です。

変更を GitHub リポジトリに push するには:

git push

git push の最中に更新が拒否されるというエラー メッセージが表示された場合は（git pull の実行を忘れた可能性があります）、最新の変更と統合してリモート リポジトリに変更を push する方法は次のとおりです。 

git pull
git commit
git push

問題をクローズする

コードレビュー ツールで問題を必ずクローズしてください。手順は次のとおりです。

  1. codereview.appspot.com の問題を選択する
  2. 左上の [Id] の前にある [X] をクリックします。

変更セットのパッチ適用解除

なんらかの理由で、インポートした変更セットを commit しない場合は、次のコマンドを使用して削除します。注意: ローカルの変更がすべて文字どおり消去されます。 

git checkout -- .