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 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.)
Setting up the development environment
Windows users, consider installing GitHub for Windows.
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-api-dotnet-client.git
To check out the samples repository, run the following:
git clone https://github.com/google/google-api-dotnet-client-samples.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-api-dotnet-client.git
To check out the samples repository, run the following:
git clone firstname.lastname@example.org:google/google-api-dotnet-client-samples.git
To switch to an alternative branch, for example 1.8:
git checkout --track origin/1.8
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:
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): email@example.com Password for firstname.lastname@example.org: your application-specific password
Windows users, please note: to run the upload.py (or any other Python script files), you should associate .py files to Python with the following commands:
ftype PythonFileType=PATH_TO_PYTHON.EXE "%0" %* assoc .py=PythonFileType
Preparing your code for review
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-api-dotnet-client --send_mail -r reviewer@somedomain --cc cc@somedomain
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-api-dotnet-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
Windows users: note that
patch may fail if the diff file is in Unix format.
You should convert the file using a converter like Unix2Dos.
To double-check that you've imported the correct diff, do a
in your working tree.
Testing the changeset
Make sure you run all unit tests before approving the changeset.
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 -- .