How to Contribute

Contributor License Agreements (CLAs)

Before we can accept your code patches, you need to submit either an individual or a corporate Contributor License Agreement (CLA):

  • If you are an individual writing original source code and you're certain that you own the intellectual property, submit an individual CLA.
  • If you work for a company, your company must submit a corporate CLA to indicate that you are allowed to contribute your work to this client library.

Follow either of the two links above to access the appropriate CLA and instructions for how to sign and return it. Once we receive it, we can add you to the official list of contributors.

Overview of submitting patches

To contribute code to this project, follow these general steps:

  1. Sign a Contributor License Agreement, as described above.
  2. Join our discussion group.
  3. Set up your development environment.
  4. Associate each of your changesets with an Issue (a bug report or feature request) in our GitHub Issue Tracker. Create a new Issue if there isn't one already, and assign it to yourself.
  5. Check out code, create a new issue on codereview.appspot.com, and complete the code review process. Detailed instructions for all these processes are given below.
  6. After your code is reviewed and you receive approval, commit the code. If you are not an official Contributor, a Contributor pulls your changeset into the official repository.

We use the following tools and processes:

  • We use Git as our version control system.
  • We use Maven for the build system, as well as a binary distribution system.
  • We use codereview.appspot.com for code reviews. (But note that in the codereview.appspot.com tool, the term "issue" means a code-review request, while in the GitHub Issue Tracker, an "issue" is a feature request or bug report.)

If you are an Eclipse developer, use the project-specific code formatting specified in the .settings directory that is automatically processed by Eclipse.

Setting up the development environment

Prerequisites

  1. Install Java 6. You might need to set your JAVA_HOME variable.
  2. Install Maven. (This document assumes you have basic familiarity with Maven commands.)
  3. Optional: Install the Android SDK and set your ANDROID_HOME variable to the install location for Android.
  4. Install Git.

Setting up Git

Use the git config command to set your default display name and email address:

git config --global user.name "YOUR NAME"
git config --global user.email "YOUR EMAIL ADDRESS"

Authenticating with GitHub from Git

To be able to check out the code from GitHub, you must be authenticated with GitHub using either HTTP or SSH. Before you continue with the instructions below, read the GitHub instructions on how to get started with HTTPS or SSH cloning. If you want to learn more about Git in general, Pro Git is a good resource.

Checking out the code

Using HTTPS

To check out the library repository in the development "master" branch, run the following command:

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

Using SSH

To check out the library repository in the development "master" branch, make sure you have write access to the GitHub repository, then run the following command:

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

To switch to an alternative branch, for example 1.12:

git checkout --track origin/1.12

To switch back to the master branch:

git checkout master

To pull in the latest changes from the GitHub repository and update your local working tree to the latest commit:

git pull

Maven

Install Google Play Services

The first time you set up the project, you need to install the google-play-services.jar file. To do this:

  1. Launch Eclipse and select Window > Android SDK Manager, or run android at the command line.
  2. Scroll to the bottom of the package list and select 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

Compile the project

mvn clean install

Maven installs the compiled binaries to a local repository (for example ~/.m2/repository). It searches for binaries in that repository before fetching from the Maven central repository.

Note: This library depends on google-http-java-client and google-oauth-java-client. When working on a new version of all three libraries that are not yet released to Maven central, you must compile them in the following order:

  1. google-http-java-client
  2. google-oauth-java-client
  3. google-api-java-client Compiling in this order ensures that Maven picks up the compiled binaries for dependent library compilation.

Code review process

Downloading the upload.py script

Download the upload.py script and optionally add it to your PATH.

The first time you run upload.py, it asks you for an application-specific password:

Email (login for uploading to codereview.appspot.com): your_email_address@yourdomain.com
Password for your_email_address@yourdomain.com:

Preparing your code for review

Before you send the code for review, you must run Clirr to catch backwards compatibility problems in your code. If any errors are reported, you need to either fix them or update the clirr-ignored-differences.xml file.

mvn -q clirr:check

You must also run the FindBugs tool to catch bugs in the code. If any errors are reported, you need to either fix them or update the findbugs-exclude.xml file. (Note that FindBugs is very slow.)

mvn findbugs:check

Once your change passes all tests, add the change to the index (the Git staging area):

git add .

Double-check that all the files you added, modified, or deleted are reflected in the index:

git status

In the git status output, check the section called "Changes to be committed."

Starting the code review

When ready for review, create a new issue on codereview.appspot.com: 

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

After you make more changes, stage your new changes. To upload a new patch, for example to issue number 123456, run the following command: 

upload.py --rev=HEAD -i 123456

For more options, run upload.py --help.

If you prefer the typical GitHub workflow, you probably have forked the GitHub repository and created a branch for this new feature or bug fix. When you send code review requests from your own fork, make sure that your fork is in sync with the upstream repository. For more information, see the GitHub help on how to sync a fork.

You can use upload.py for locally committed changesets, too.

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

Code reviewer

If you are a code reviewer, import and test changesets before you approve them, and then commit and push the changesets to the remote repository.

Importing a changeset

To catch errors early, be sure to pull the latest changes from the remote repository into your working tree. Make sure your working tree is clean and your index is empty.

To pull and merge latest commits from the remote repository:

git pull

To check what's in your working tree and index:

git status

To import a patch into your local Git clone:

  1. Open the issue within codereview.appspot.com.
  2. For the patch in question, look for "Download raw" at the top right of the patch specification.
  3. Click "raw" to get a URL for the file to import.
  4. Save the raw diff file to your local machine with a name such as issue123456.diff.
  5. Go to your local Git working tree and apply the diff using the patch command:
patch -p1 < issue123456.diff

To double-check that you've imported the correct diff, do a git diff in your working tree.

Testing the changeset

To run the tests and install, use the following command:

mvn clean install checkstyle:check

Approving a changeset on codereview.appspot.com

In general, code cannot be pushed to the GitHub repository until the code reviewer is satisfied that the code is ready. At that point, the convention is to reply with the message "LGTM" (Looks Good To Me).

Committing the code

Important: Before you commit your code, pull the latest changes into your working tree and update your working tree to the latest commit from the GitHub repository:

git pull

If there are any conflicts, resolve them, then be sure to get all tests to pass again.

To commit the code locally: 

git commit

Enter a message such as the following (assuming you are fixing or implementing Issue # 123, as listed in the GitHub Issue Tracker):

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

Before the first colon and the description:

  • If this is a fix to a problem on the Issue Tracker, include the issue number, as shown.
  • If this is a change for a particular branch, include the branch number.
  • You will be the committer of this commit, but please give credit to the author of the change by marking them as the author (--author=<author>).

Following the description, always include a link to the issue on the codereview site. This link is important because without it, there's no convenient way to figure out the code review associated with a commit, which is useful for maintaining a history of the discussion.

To push the change to the GitHub repository:

git push

If during git push you get an error message about updates being rejected (perhaps you forgot to run git pull), here's how to merge with the latest changes and push your changes to the remote repository: 

git pull
git commit
git push

Closing the issue

Make sure to close the issue in the code-review tool. To do this:

  1. Select the issue in codereview.appspot.com.
  2. Click the "X" that is at the top-left, preceding "Id."

Unpatching a changeset

If for some reason you decide not to commit a changeset you imported, use the following command to get rid it. Be careful: It literally erases all of your local changes. 

git checkout -- .