## 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](https://cla.developers.google.com/about/google-individual).
- If you work for a company, your company must submit a [corporate CLA](https://developers.google.com/open-source/cla/corporate) 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](http://groups.google.com/group/google-api-java-client).
3. Set up your [development environment](https://developers.google.com/api-client-library/java/google-api-java-client/contribute#environment).
4. Associate each of your changesets with an Issue (a bug report or feature request) in our GitHub [Issue Tracker](https://github.com/google/google-api-java-client/issues). 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](http://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](http://git-scm.com/) as our version control system.
- We use [Maven](http://maven.apache.org/) for the build system, as well as a binary distribution system.
- We use [codereview.appspot.com](http://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](http://java.com). You might need to set your `JAVA_HOME` variable.
2. Install [Maven](http://maven.apache.org/download.html). (This document assumes you have basic familiarity with Maven commands.)
3. Optional: Install the [Android SDK](http://developer.android.com/sdk/index.html) and set your ANDROID_HOME variable to the install location for Android.
4. Install [Git](http://git-scm.com/).

### Setting up Git

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

```java
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](https://help.github.com/articles/set-up-git/) on how to get
started with HTTPS or SSH cloning. If you want to learn more about Git in
general, [Pro Git](http://git-scm.com/book/en/v2) 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:

```java
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:

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

To switch to an alternative branch, for example 1.12:

```java
git checkout --track origin/1.12
```

To switch back to the master branch:

```java
git checkout master
```

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

```java
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**.

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

```java
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](http://search.maven.org/#search%7Cga%7C1%7C).

**Note:**
This library depends on [google-http-java-client](https://github.com/google/google-http-java-client)
and [google-oauth-java-client](https://github.com/google/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](http://codereview.appspot.com/static/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](https://support.google.com/accounts/answer/185833):

```java
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.

```java
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.)

```java
mvn findbugs:check
```

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

```java
git add .
```

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

```java
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:

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

<br />

> [!NOTE]
> **Tip:** If you want the issue to be visible to reviewers and those who are included on the CC line only, use the `--private` option.

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

```java
upload.py --rev=HEAD -i 123456
```

<br />

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

If you prefer the typical [GitHub
workflow](https://guides.github.com/introduction/flow/index.html),
you probably have [forked](https://help.github.com/articles/fork-a-repo/) 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](https://help.github.com/articles/syncing-a-fork/).

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

```java
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:

```java
git pull
```

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

```java
git status
```

To import a patch into your local Git clone:

1. Open the issue within [codereview.appspot.com](http://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:

```java
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:

```java
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:

```java
git pull
```

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

To commit the code **locally**:

```java
git commit
```

<br />

Enter a message such as the following (assuming you are fixing or implementing
Issue # 123, as listed in the GitHub
[Issue Tracker](https://github.com/google/google-api-java-client/issues)):

```java
#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](https://github.com/google/google-api-java-client/issues), 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:

```java
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:

```java
git pull
git commit
git push
```

<br />

### 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](http://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.

```java
git checkout -- .
```

<br />