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:
- Sign a Contributor License Agreement, as described above.
- Join our discussion group.
- Set up your development environment.
- 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.
- 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.
- 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
- Install Java 6. You might need to set your
- Install Maven. (This document assumes you have basic familiarity with Maven commands.)
- Optional: Install the Android SDK and set your ANDROID_HOME variable to the install location for Android.
- Install Git.
- Install protobuf version 2.4.1.
Download and unzip http://protobuf.googlecode.com/files/protobuf-2.4.1.zip (for example to ~/Downloads), and then run the following commands:
cd ~/Downloads/protobuf-2.4.1 ./configure --prefix=/usr make make check sudo make install
Read the instructions at the top of the protobuf-2.4.1/README.txt file, including the "Hint on install location" section.
Setting up Git
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
To check out the library repository in the development "master" branch, run the following command:
git clone https://github.com/google/google-http-java-client.git
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 email@example.com:google/google-http-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:
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:
- Select Window > Preferences... (or on Mac, Eclipse > Preferences...).
- (Optional) Under General > Appearance > Label Decorations, check on "Maven Version Decorator."
- (Optional) Under General > Editors > Text Editors, set print margin column to 100.
- (Optional) For Maven:
- Check on "Download Artifact Sources."
- Check on "Download Artifact JavaDoc."
- 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
so on), run the following command:
To import the project to an Eclipse workspace:
- From within Eclipse, select File > Import....
- Select General > Existing Project into Workspace and click Next.
- Next to Select root directory, browse to the directory where your project is synced (for example google-http-java-client) and click OK.
- Click Next and Finish.
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
- From within Eclipse, select Window > Preferences (or on Mac, Eclipse > Preferences...).
- Select Java > Build Path > Classpath Variables.
- Click New....
M2_REPOas the name, and choose the local Maven repository, for example ~/.m2/repository.
- Click OK. Eclipse reminds you to rebuild all projects to work with the new classpath variable.
- Click Done.
You only need to add
M2_REPO once, and it is shared among all of your Eclipse
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
Email (login for uploading to codereview.appspot.com): firstname.lastname@example.org Password for email@example.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.)
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 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-http-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
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-http-java-client --send_mail -r reviewer@somedomain --cc ...
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:
To check what's in your working tree and index:
To import a patch into your local Git clone:
- Open the issue within codereview.appspot.com.
- For the patch in question, look for "Download raw" at the top right of the patch specification.
- Click "raw" to get a URL for the file to import.
- Save the raw diff file to your local machine with a name such as issue123456.diff.
- Go to your local Git working tree and apply the diff using the
patch -p1 < issue123456.diff
To double-check that you've imported the correct diff, do a
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:
If there are any conflicts, resolve them, then be sure to get all tests to pass again.
To commit the code locally:
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
committerof this commit, but please give credit to the author of the change by marking them as the
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 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:
- Select the issue in codereview.appspot.com.
- 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 -- .