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 pull requests 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 pull request on GitHub with your changes, and complete the code review process. Detailed instructions for 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 merges your pull request 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.

Setting up the development environment


  1. Install Java 7. 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.
  5. Install protobuf version 2.4.1.

Setting up Git

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

git config --global "YOUR NAME"
git config --global "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


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

git clone

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

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


To clean, compile, test, and install the project, run the following command:

mvn clean install


Prerequisites for using Eclipse:

To set your preferences within Eclipse:

  1. Select Window > Preferences... (or on Mac, Eclipse > Preferences...).
  2. (Optional) Under General > Appearance > Label Decorations, check on "Maven Version Decorator."
  3. (Optional) Under General > Editors > Text Editors, set print margin column to 100.
  4. (Optional) For Maven:
    • Check on "Download Artifact Sources."
    • Check on "Download Artifact JavaDoc."
  5. For Android, set up the SDK location.

Importing to Eclipse

The project is designed to work well with Eclipse. To convert the Maven project to an Eclipse project (that is, to create .classpath, and so on), run the following command:

mvn eclipse:eclipse

To import the project to an Eclipse workspace:

  1. From within Eclipse, select File > Import....
  2. Select General > Existing Project into Workspace and click Next.
  3. Next to Select root directory, browse to the directory where your project is synced (for example google-http-java-client) and click OK.
  4. Click Next and Finish.

Adding the M2_REPO classpath variable to Eclipse

When you run mvn eclipse:eclipse, Maven creates the entire dependency classpath by using the M2_REPO variable, which is not defined in Eclipse by default. To add the M2_REPO classpath variable into the Eclipse IDE, follow these instructions:

  1. From within Eclipse, select Window > Preferences (or on Mac, Eclipse > Preferences...).
  2. Select Java > Build Path > Classpath Variables.
  3. Click New....
  4. Type M2_REPO as the name, and choose the local Maven repository, for example ~/.m2/repository.
  5. Click OK. Eclipse reminds you to rebuild all projects to work with the new classpath variable.
  6. Click Done.

You only need to add M2_REPO once, and it is shared among all of your Eclipse workspaces.

Code review process

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."

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
  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

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

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