1 Contributing 2 ============ 3 4 1. **Please sign one of the contributor license agreements [below][6].** 5 1. [File an issue][9] to notify the maintainers about what you're working on. 6 1. [Fork the repo][10], develop and [test][11] your code changes, add docs. 7 1. Make sure that your commit messages clearly describe the changes. 8 1. [Send][12] a pull request. 9 10 Here are some guidelines for hacking on `oauth2client`. 11 12 Before writing code, file an issue 13 ---------------------------------- 14 15 Use the [issue tracker][7] to start the discussion. It is possible that someone 16 else is already working on your idea, your approach is not quite right, or that 17 the functionality exists already. The ticket you file in the issue tracker will 18 be used to hash that all out. 19 20 Fork `oauth2client` 21 ------------------- 22 23 We will use GitHub's mechanism for [forking][8] repositories and making pull 24 requests. Fork the repository, and make your changes in the forked repository. 25 26 Include tests 27 ------------- 28 29 Be sure to add the relevant tests before making the pull request. Docs will be 30 updated automatically when we merge to `master`, but you should also build 31 the docs yourself via `tox -e docs` and make sure they're readable. 32 33 Make the pull request 34 --------------------- 35 36 Once you have made all your changes, tests, and updated the documentation, 37 make a pull request to move everything back into the main `oauth2client` 38 repository. Be sure to reference the original issue in the pull request. 39 Expect some back-and-forth with regards to style and compliance of these 40 rules. In particular: 41 * `oauth2client` follows the [Google Python Style Guide][GooglePythonStyle]. 42 * Follow [these guidelines][GitCommitRules] when authoring your commit message. 43 44 Using a Development Checkout 45 ---------------------------- 46 47 Youll have to create a development environment to hack on 48 `oauth2client`, using a Git checkout: 49 50 - While logged into your GitHub account, navigate to the `oauth2client` 51 [repo][1] on GitHub. 52 - Fork and clone the `oauth2client` repository to your GitHub account 53 by clicking the "Fork" button. 54 - Clone your fork of `oauth2client` from your GitHub account to your 55 local computer, substituting your account username and specifying 56 the destination as `hack-on-oauth2client`. For example: 57 58 ```bash 59 $ cd ${HOME} 60 $ git clone git (a] github.com:USERNAME/oauth2client.git hack-on-oauth2client 61 $ cd hack-on-oauth2client 62 $ # Configure remotes such that you can pull changes from the oauth2client 63 $ # repository into your local repository. 64 $ git remote add upstream https://github.com:google/oauth2client 65 $ # fetch and merge changes from upstream into master 66 $ git fetch upstream 67 $ git merge upstream/master 68 ``` 69 70 Now your local repo is set up such that you will push changes to your 71 GitHub repo, from which you can submit a pull request. 72 73 - Create a virtualenv in which to install `oauth2client`: 74 75 ```bash 76 $ cd ~/hack-on-oauth2client 77 $ virtualenv -ppython2.7 env 78 ``` 79 80 Note that very old versions of virtualenv (virtualenv versions 81 below, say, 1.10 or thereabouts) require you to pass a 82 `--no-site-packages` flag to get a completely isolated environment. 83 84 You can choose which Python version you want to use by passing a 85 `-p` flag to `virtualenv`. For example, `virtualenv -ppython2.7` 86 chooses the Python 2.7 interpreter to be installed. 87 88 From here on in within these instructions, the 89 `~/hack-on-oauth2client/env` virtual environment you created above will be 90 referred to as `$VENV`. To use the instructions in the steps that 91 follow literally, use the `export VENV=~/hack-on-oauth2client/env` 92 command. 93 94 - Install `oauth2client` from the checkout into the virtualenv using 95 `setup.py develop`. Running `setup.py develop` **must** be done while 96 the current working directory is the `oauth2client` checkout 97 directory: 98 99 ```bash 100 $ cd ~/hack-on-oauth2client 101 $ $VENV/bin/python setup.py develop 102 ``` 103 104 Running Tests 105 -------------- 106 107 - To run all tests for `oauth2client` on a single Python version, run 108 `nosetests` from your development virtualenv (See 109 **Using a Development Checkout** above). 110 111 - To run the full set of `oauth2client` tests on all platforms, install 112 [`tox`][2] into a system Python. The `tox` console script will be 113 installed into the scripts location for that Python. While in the 114 `oauth2client` checkout root directory (it contains `tox.ini`), 115 invoke the `tox` console script. This will read the `tox.ini` file and 116 execute the tests on multiple Python versions and platforms; while it runs, 117 it creates a virtualenv for each version/platform combination. For 118 example: 119 120 ```bash 121 $ sudo pip install tox 122 $ cd ~/hack-on-oauth2client 123 $ tox 124 ``` 125 126 - In order to run the `pypy` environment (in `tox`) you'll need at 127 least version 2.6 of `pypy` installed. See the [docs][13] for 128 more information. 129 130 - **Note** that `django` related tests are turned off for Python 2.6 131 and 3.3. This is because `django` dropped support for 132 [2.6 in `django==1.7`][14] and for [3.3 in `django==1.9`][15]. 133 134 Running System Tests 135 -------------------- 136 137 - To run system tests you can execute: 138 139 ```bash 140 $ tox -e system-tests 141 $ tox -e system-tests3 142 ``` 143 144 This alone will not run the tests. You'll need to change some local 145 auth settings and download some service account configuration files 146 from your project to run all the tests. 147 148 - System tests will be run against an actual project and so you'll need to 149 provide some environment variables to facilitate this. 150 151 - `OAUTH2CLIENT_TEST_JSON_KEY_PATH`: The path to a service account JSON 152 key file; see `tests/data/gcloud/application_default_credentials.json` 153 as an example. Such a file can be downloaded directly from the 154 developer's console by clicking "Generate new JSON key". See private 155 key [docs][3] for more details. 156 - `OAUTH2CLIENT_TEST_P12_KEY_PATH`: The path to a service account 157 P12/PKCS12 key file. You can download this in the same way as a JSON 158 key, just select "P12 Key" as your "Key type" when downloading. 159 - `OAUTH2CLIENT_TEST_P12_KEY_EMAIL`: The service account email 160 corresponding to the P12/PKCS12 key file. 161 - `OAUTH2CLIENT_TEST_USER_KEY_PATH`: The path to a JSON key file for a 162 user. If this is not set, the file created by running 163 `gcloud auth login` will be used. See 164 `tests/data/gcloud/application_default_credentials_authorized_user.json` 165 for an example. 166 - `OAUTH2CLIENT_TEST_USER_KEY_EMAIL`: The user account email 167 corresponding to the user JSON key file. 168 169 - Examples of these can be found in `scripts/local_test_setup.sample`. We 170 recommend copying this to `scripts/local_test_setup`, editing the values 171 and sourcing them into your environment: 172 173 ```bash 174 $ source scripts/local_test_setup 175 ``` 176 177 Contributor License Agreements 178 ------------------------------ 179 180 Before we can accept your pull requests you'll need to sign a Contributor 181 License Agreement (CLA): 182 183 - **If you are an individual writing original source code** and **you own 184 the intellectual property**, then you'll need to sign an 185 [individual CLA][4]. 186 - **If you work for a company that wants to allow you to contribute your 187 work**, then you'll need to sign a [corporate CLA][5]. 188 189 You can sign these electronically (just scroll to the bottom). After that, 190 we'll be able to accept your pull requests. 191 192 [1]: https://github.com/google/oauth2client 193 [2]: https://tox.readthedocs.io/en/latest/ 194 [3]: https://cloud.google.com/storage/docs/authentication#generating-a-private-key 195 [4]: https://developers.google.com/open-source/cla/individual 196 [5]: https://developers.google.com/open-source/cla/corporate 197 [6]: #contributor-license-agreements 198 [7]: https://github.com/google/oauth2client/issues 199 [8]: https://help.github.com/articles/fork-a-repo/ 200 [9]: #before-writing-code-file-an-issue 201 [10]: #fork-oauth2client 202 [11]: #include-tests 203 [12]: #make-the-pull-request 204 [13]: https://oauth2client.readthedocs.io/en/latest/#using-pypy 205 [14]: https://docs.djangoproject.com/en/1.7/faq/install/#what-python-version-can-i-use-with-django 206 [15]: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django 207 [GooglePythonStyle]: https://google.github.io/styleguide/pyguide.html 208 [GitCommitRules]: http://chris.beams.io/posts/git-commit/#seven-rules 209
