Contributing Code to gsutil

Overview

We're open to incorporating gsutil code changes authored by users. Here are some guidelines:

Before we can accept code submissions, we have to jump a couple of legal hurdles. Please fill out either the individual or corporate Contributor License Agreement:
- If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an individual CLA (https://cla.developers.google.com/about/google-individual).
- If you work for a company that wants to allow you to contribute your work to gsutil, then you'll need to sign a corporate CLA (https://cla.developers.google.com/about/google-corporate)
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'll add you to the official list of contributors and be able to accept your patches.
If you found a bug or have an idea for a feature enhancement, we suggest you check https://github.com/GoogleCloudPlatform/gsutil/issues to see if it has already been reported by another user. From there you can also subscribe to updates to the issue.

If a GitHub issue doesn't already exist, create one about your idea before sending actual code. Often we can discuss the idea and help propose things that could save you later revision work.
We tend to avoid adding command line options that are of use to only a very small fraction of users, especially if there's some other way to accommodate such needs. Adding such options complicates the code and also adds overhead to users having to read through an "alphabet soup" list of option documentation.
While gsutil has a number of features specific to Cloud Storage, it can also be used with other cloud storage providers. We're open to including changes for making gsutil support features specific to other providers, as long as those changes don't make gsutil work worse for Cloud Storage. If you do make such changes we recommend including someone with knowledge of the specific provider as a code reviewer (see below).
You can check out the gsutil code from the GitHub repository:
```
https://github.com/GoogleCloudPlatform/gsutil
```
To clone a read-only copy of the repository:
```
git clone git://github.com/GoogleCloudPlatform/gsutil.git
```
To push your own changes to GitHub, click the Fork button on the repository page and clone the repository from your own fork.
The gsutil git repository uses git submodules to pull in external modules. After checking out the repository, make sure to also pull the submodules by entering into the gsutil top-level directory and run:
```
git submodule update --init --recursive
```
Please make sure to run all tests against your modified code. To do this, change directories into the gsutil top-level directory and run:
```
./gsutil test
```
The above tests take a long time to run because they send many requests to the production service. The gsutil test command has a -u argument that will only run unit tests. These run quickly, as they are executed with an in-memory mock storage service implementation. To run only the unit tests, run:
```
./gsutil test -u
```
If you made changes to boto, please run the boto tests. For these tests you need to use HMAC credentials (from gsutil config -a), because the boto test suite doesn't import the OAuth2 handler. You'll also need to install some python modules. Change directories into the boto root directory at third_party/boto and run:
```
pip install -r requirements.txt
```
(You probably need to run this command using sudo.) Make sure each of the individual installations succeeded. If they don't you may need to run the install command again.

Then ensure your .boto file has HMAC credentials defined, and then change directories into boto's tests directory and run:
```
python test.py unit
python test.py -t s3 -t gs -t ssl
```
Please consider contributing test code for your change, especially if the change impacts any of the core gsutil code (like the gsutil cp command).
Please run the yapf linter with the config files in the root of the GitHub repository:
```
yapf -irp .
```
When it's time to send us code, please submit a PR to the gsutil GitHub repository. For help on making GitHub PRs, please refer to this GitHub help document.