OLD | NEW |
(Empty) | |
| 1 Contributing |
| 2 ============ |
| 3 |
| 4 1. **Please sign one of the contributor license agreements below.** |
| 5 1. Fork the repo, develop and test your code changes, add docs. |
| 6 1. Make sure that your commit messages clearly describe the changes. |
| 7 1. Send a pull request. |
| 8 |
| 9 Here are some guidelines for hacking on `oauth2client`. |
| 10 |
| 11 Using a Development Checkout |
| 12 ---------------------------- |
| 13 |
| 14 You’ll have to create a development environment to hack on |
| 15 `oauth2client`, using a Git checkout: |
| 16 |
| 17 - While logged into your GitHub account, navigate to the `oauth2client` |
| 18 [repo][1] on GitHub. |
| 19 - Fork and clone the `oauth2client` repository to your GitHub account |
| 20 by clicking the "Fork" button. |
| 21 - Clone your fork of `oauth2client` from your GitHub account to your |
| 22 local computer, substituting your account username and specifying |
| 23 the destination as `hack-on-oauth2client`. For example: |
| 24 |
| 25 ```bash |
| 26 $ cd ${HOME} |
| 27 $ git clone git@github.com:USERNAME/oauth2client.git hack-on-oauth2client |
| 28 $ cd hack-on-oauth2client |
| 29 $ # Configure remotes such that you can pull changes from the oauth2client |
| 30 $ # repository into your local repository. |
| 31 $ git remote add upstream https://github.com:google/oauth2client |
| 32 $ # fetch and merge changes from upstream into master |
| 33 $ git fetch upstream |
| 34 $ git merge upstream/master |
| 35 ``` |
| 36 |
| 37 Now your local repo is set up such that you will push changes to your |
| 38 GitHub repo, from which you can submit a pull request. |
| 39 |
| 40 - Create a virtualenv in which to install `oauth2client`: |
| 41 |
| 42 ```bash |
| 43 $ cd ~/hack-on-oauth2client |
| 44 $ virtualenv -ppython2.7 env |
| 45 ``` |
| 46 |
| 47 Note that very old versions of virtualenv (virtualenv versions |
| 48 below, say, 1.10 or thereabouts) require you to pass a |
| 49 `--no-site-packages` flag to get a completely isolated environment. |
| 50 |
| 51 You can choose which Python version you want to use by passing a |
| 52 `-p` flag to `virtualenv`. For example, `virtualenv -ppython2.7` |
| 53 chooses the Python 2.7 interpreter to be installed. |
| 54 |
| 55 From here on in within these instructions, the |
| 56 `~/hack-on-oauth2client/env` virtual environment you created above will be |
| 57 referred to as `$VENV`. To use the instructions in the steps that |
| 58 follow literally, use the `export VENV=~/hack-on-oauth2client/env` |
| 59 command. |
| 60 |
| 61 - Install `oauth2client` from the checkout into the virtualenv using |
| 62 `setup.py develop`. Running `setup.py develop` **must** be done while |
| 63 the current working directory is the `oauth2client` checkout |
| 64 directory: |
| 65 |
| 66 ```bash |
| 67 $ cd ~/hack-on-oauth2client |
| 68 $ $VENV/bin/python setup.py develop |
| 69 ``` |
| 70 |
| 71 Running Tests |
| 72 -------------- |
| 73 |
| 74 - To run all tests for `oauth2client` on a single Python version, run |
| 75 `nosetests` from your development virtualenv (See |
| 76 **Using a Development Checkout** above). |
| 77 |
| 78 - To run the full set of `oauth2client` tests on all platforms, install |
| 79 [`tox`][2] into a system Python. The `tox` console script will be |
| 80 installed into the scripts location for that Python. While in the |
| 81 `oauth2client` checkout root directory (it contains `tox.ini`), |
| 82 invoke the `tox` console script. This will read the `tox.ini` file and |
| 83 execute the tests on multiple Python versions and platforms; while it runs, |
| 84 it creates a virtualenv for each version/platform combination. For |
| 85 example: |
| 86 |
| 87 ```bash |
| 88 $ sudo pip install tox |
| 89 $ cd ~/hack-on-oauth2client |
| 90 $ tox |
| 91 ``` |
| 92 |
| 93 Running System Tests |
| 94 -------------------- |
| 95 |
| 96 - To run system tests you can execute: |
| 97 |
| 98 ```bash |
| 99 $ tox -e system-tests |
| 100 $ tox -e system-tests3 |
| 101 ``` |
| 102 |
| 103 This alone will not run the tests. You'll need to change some local |
| 104 auth settings and download some service account configuration files |
| 105 from your project to run all the tests. |
| 106 |
| 107 - System tests will be run against an actual project and so you'll need to |
| 108 provide some environment variables to facilitate this. |
| 109 |
| 110 - `OAUTH2CLIENT_TEST_JSON_KEY_PATH`: The path to a service account JSON |
| 111 key file; see `tests/data/gcloud/application_default_credentials.json` |
| 112 as an example. Such a file can be downloaded directly from the |
| 113 developer's console by clicking "Generate new JSON key". See private |
| 114 key [docs][3] for more details. |
| 115 - `OAUTH2CLIENT_TEST_P12_KEY_PATH`: The path to a service account |
| 116 P12/PKCS12 key file. You can download this in the same way as a JSON |
| 117 key, just select "P12 Key" as your "Key type" when downloading. |
| 118 - `OAUTH2CLIENT_TEST_P12_KEY_EMAIL`: The service account email |
| 119 corresponding to the P12/PKCS12 key file. |
| 120 - `OAUTH2CLIENT_TEST_USER_KEY_PATH`: The path to a JSON key file for a |
| 121 user. If this is not set, the file created by running |
| 122 `gcloud auth login` will be used. See |
| 123 `tests/data/gcloud/application_default_credentials_authorized_user.json` |
| 124 for an example. |
| 125 - `OAUTH2CLIENT_TEST_USER_KEY_EMAIL`: The user account email |
| 126 corresponding to the user JSON key file. |
| 127 |
| 128 - Examples of these can be found in `scripts/local_test_setup.sample`. We |
| 129 recommend copying this to `scripts/local_test_setup`, editing the values |
| 130 and sourcing them into your environment: |
| 131 |
| 132 ```bash |
| 133 $ source scripts/local_test_setup |
| 134 ``` |
| 135 |
| 136 Contributor License Agreements |
| 137 ------------------------------ |
| 138 |
| 139 Before we can accept your pull requests you'll need to sign a Contributor |
| 140 License Agreement (CLA): |
| 141 |
| 142 - **If you are an individual writing original source code** and **you own |
| 143 the intellectual property**, then you'll need to sign an |
| 144 [individual CLA][4]. |
| 145 - **If you work for a company that wants to allow you to contribute your |
| 146 work**, then you'll need to sign a [corporate CLA][5]. |
| 147 |
| 148 You can sign these electronically (just scroll to the bottom). After that, |
| 149 we'll be able to accept your pull requests. |
| 150 |
| 151 [1]: https://github.com/google/oauth2client |
| 152 [2]: https://tox.readthedocs.org/en/latest/ |
| 153 [3]: https://cloud.google.com/storage/docs/authentication#generating-a-private-k
ey |
| 154 [4]: https://developers.google.com/open-source/cla/individual |
| 155 [5]: https://developers.google.com/open-source/cla/corporate |
OLD | NEW |