貢献方法

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

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

  • 元のソースコードを作成し、知的財産権を所有している個人の方は、個々の CLA をご提出ください。
  • 企業で勤務している場合は、クライアント CLA を送信して、このクライアント ライブラリに自身の投稿を提供できることを示す必要があります。

上記のいずれかのリンクをクリックして該当する CLA を取得し、署名と返信の方法を確認してください。情報を受け取ったら、コントリビューターの公式リストに追加できます。

パッチの送信の概要

このプロジェクトへのコードの投稿は、次の手順に沿って行います。

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

次のツールとプロセスを使用します。

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

Eclipse デベロッパーの場合は、Eclipse によって自動的に処理される .settings ディレクトリで指定された、プロジェクト固有のコード形式を使用します。

開発環境の設定

Prerequisites

  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 の手順をご覧ください。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 リポジトリから最新の変更を取得し、ローカル作業ツリーを最新の commit に更新するには:

git pull

Maven

Google Play 開発者サービスのインストール

プロジェクトを初めて設定するときに、google-play-services.jar ファイルをインストールする必要があります。手順は次のとおりです。

  1. Eclipse を起動して [Window > Android SDK Manager] を選択するか、コマンドラインで android を実行します。
  2. パッケージ リストの一番下までスクロールし、[Extras > Google Play services] を選択します。
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 の出力で、「commits to change to 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 のヘルプをご覧ください。

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

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. [未加工] をクリックして、インポートするファイルの URL を取得します。
  4. 未加工の差分ファイルを issue123456.diff などの名前でローカルマシンに保存します。
  5. ローカルの Git 作業ツリーに移動し、patch コマンドを使用して差分を適用します。
patch -p1 < issue123456.diff

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

変更セットのテスト

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

mvn clean install checkstyle:check

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

一般に、コードレビューアがコードの準備ができるまで、コードを GitHub リポジトリに push することはできません。この時点では、「LGTM」というメッセージを付けて返信するのが慣例となっています。

コードの 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 の問題を修正する場合は、以下のように問題の番号を記載します。
  • 特定のブランチに変更が加えられる場合は、ブランチ番号を含めます。
  • 自分がこの commit の 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 -- .