CONTRIBUTING.md - platform/external/python/oauth2client - Git at Google


            
            Contributing

            
            ============


            1.  **Please sign one of the contributor license agreements [below][6].**

            
            1.  [File an issue][9] to notify the maintainers about what you're working on.

            
            1.  [Fork the repo][10], develop and [test][11] your code changes, add docs.

            
            1.  Make sure that your commit messages clearly describe the changes.

            
            1.  [Send][12] a pull request.


            Here are some guidelines for hacking on `oauth2client`.


            Before writing code, file an issue

            
            ----------------------------------


            Use the [issue tracker][7] to start the discussion. It is possible that someone

            
            else is already working on your idea, your approach is not quite right, or that

            
            the functionality exists already. The ticket you file in the issue tracker will

            
            be used to hash that all out.


            Fork `oauth2client`

            
            -------------------


            We will use GitHub's mechanism for [forking][8] repositories and making pull

            
            requests. Fork the repository, and make your changes in the forked repository.


            Include tests

            
            -------------


            Be sure to add the relevant tests before making the pull request. Docs will be

            
            updated automatically when we merge to `master`, but you should also build

            
            the docs yourself via `tox -e docs` and make sure they're readable.


            Make the pull request

            
            ---------------------


            Once you have made all your changes, tests, and updated the documentation,

            
            make a pull request to move everything back into the main `oauth2client`

            
            repository. Be sure to reference the original issue in the pull request.

            
            Expect some back-and-forth with regards to style and compliance of these

            
            rules. In particular:

            
            * `oauth2client` follows the [Google Python Style Guide][GooglePythonStyle].

            
            * Follow [these guidelines][GitCommitRules] when authoring your commit message.


            Using a Development Checkout

            
            ----------------------------


            You’ll have to create a development environment to hack on

            
            `oauth2client`, using a Git checkout:


            -   While logged into your GitHub account, navigate to the `oauth2client`

            
                [repo][1] on GitHub.

            
            -   Fork and clone the `oauth2client` repository to your GitHub account

            
                by clicking the "Fork" button.

            
            -   Clone your fork of `oauth2client` from your GitHub account to your

            
                local computer, substituting your account username and specifying

            
                the destination as `hack-on-oauth2client`. For example:


                ```bash

            
                $ cd ${HOME}

            
                $ git clone git@github.com:USERNAME/oauth2client.git hack-on-oauth2client

            
                $ cd hack-on-oauth2client

            
                $ # Configure remotes such that you can pull changes from the oauth2client

            
                $ # repository into your local repository.

            
                $ git remote add upstream https://github.com:google/oauth2client

            
                $ # fetch and merge changes from upstream into master

            
                $ git fetch upstream

            
                $ git merge upstream/master

            
                ```


            Now your local repo is set up such that you will push changes to your

            
            GitHub repo, from which you can submit a pull request.


            -   Create a virtualenv in which to install `oauth2client`:


                ```bash

            
                $ cd ~/hack-on-oauth2client

            
                $ virtualenv -ppython2.7 env

            
                ```


                Note that very old versions of virtualenv (virtualenv versions

            
                below, say, 1.10 or thereabouts) require you to pass a

            
                `--no-site-packages` flag to get a completely isolated environment.


                You can choose which Python version you want to use by passing a

            
                `-p` flag to `virtualenv`. For example, `virtualenv -ppython2.7`

            
                chooses the Python 2.7 interpreter to be installed.


                From here on in within these instructions, the

            
                `~/hack-on-oauth2client/env` virtual environment you created above will be

            
                referred to as `$VENV`. To use the instructions in the steps that

            
                follow literally, use the `export VENV=~/hack-on-oauth2client/env`

            
                command.


            -   Install `oauth2client` from the checkout into the virtualenv using

            
                `setup.py develop`. Running `setup.py develop` **must** be done while

            
                the current working directory is the `oauth2client` checkout

            
                directory:


                ```bash

            
                $ cd ~/hack-on-oauth2client

            
                $ $VENV/bin/python setup.py develop

            
                ```


            Running Tests

            
            --------------


            -   To run all tests for `oauth2client` on a single Python version, run

            
                `nosetests` from your development virtualenv (See

            
                **Using a Development Checkout** above).


            -   To run the full set of `oauth2client` tests on all platforms, install

            
                [`tox`][2] into a system Python.  The `tox` console script will be

            
                installed into the scripts location for that Python.  While in the

            
                `oauth2client` checkout root directory (it contains `tox.ini`),

            
                invoke the `tox` console script.  This will read the `tox.ini` file and

            
                execute the tests on multiple Python versions and platforms; while it runs,

            
                it creates a virtualenv for each version/platform combination.  For

            
                example:


                ```bash

            
                $ sudo pip install tox

            
                $ cd ~/hack-on-oauth2client

            
                $ tox

            
                ```


            -   In order to run the `pypy` environment (in `tox`) you'll need at

            
                least version 2.6 of `pypy` installed. See the [docs][13] for

            
                more information.


            -   **Note** that `django` related tests are turned off for Python 2.6

            
                and 3.3. This is because `django` dropped support for

            
                [2.6 in `django==1.7`][14] and for [3.3 in `django==1.9`][15].


            Running System Tests

            
            --------------------


            -   To run system tests you can execute:


                ```bash

            
                $ tox -e system-tests

            
                $ tox -e system-tests3

            
                ```


                This alone will not run the tests. You'll need to change some local

            
                auth settings and download some service account configuration files

            
                from your project to run all the tests.


            -   System tests will be run against an actual project and so you'll need to

            
                provide some environment variables to facilitate this.


                -   `OAUTH2CLIENT_TEST_JSON_KEY_PATH`: The path to a service account JSON

            
                    key file; see `tests/data/gcloud/application_default_credentials.json`

            
                    as an example. Such a file can be downloaded directly from the

            
                    developer's console by clicking "Generate new JSON key". See private

            
                    key [docs][3] for more details.

            
                -   `OAUTH2CLIENT_TEST_P12_KEY_PATH`: The path to a service account

            
                    P12/PKCS12 key file. You can download this in the same way as a JSON

            
                    key, just select "P12 Key" as your "Key type" when downloading.

            
                -   `OAUTH2CLIENT_TEST_P12_KEY_EMAIL`: The service account email

            
                    corresponding to the P12/PKCS12 key file.

            
                -   `OAUTH2CLIENT_TEST_USER_KEY_PATH`: The path to a JSON key file for a

            
                    user. If this is not set, the file created by running

            
                    `gcloud auth login` will be used. See

            
                    `tests/data/gcloud/application_default_credentials_authorized_user.json`

            
                    for an example.

            
                -   `OAUTH2CLIENT_TEST_USER_KEY_EMAIL`: The user account email

            
                    corresponding to the user JSON key file.


            -   Examples of these can be found in `scripts/local_test_setup.sample`. We

            
                recommend copying this to `scripts/local_test_setup`, editing the values

            
                and sourcing them into your environment:


                ```bash

            
                $ source scripts/local_test_setup

            
                ```


            Contributor License Agreements

            
            ------------------------------


            Before we can accept your pull requests you'll need to sign a Contributor

            
            License Agreement (CLA):


            -   **If you are an individual writing original source code** and **you own

            
                the intellectual property**, then you'll need to sign an

            
                [individual CLA][4].

            
            -   **If you work for a company that wants to allow you to contribute your

            
                work**, then you'll need to sign a [corporate CLA][5].


            You can sign these electronically (just scroll to the bottom). After that,

            
            we'll be able to accept your pull requests.


            [1]: https://github.com/google/oauth2client

            
            [2]: https://tox.readthedocs.io/en/latest/

            
            [3]: https://cloud.google.com/storage/docs/authentication#generating-a-private-key

            
            [4]: https://developers.google.com/open-source/cla/individual

            
            [5]: https://developers.google.com/open-source/cla/corporate

            
            [6]: #contributor-license-agreements

            
            [7]: https://github.com/google/oauth2client/issues

            
            [8]: https://help.github.com/articles/fork-a-repo/

            
            [9]: #before-writing-code-file-an-issue

            
            [10]: #fork-oauth2client

            
            [11]: #include-tests

            
            [12]: #make-the-pull-request

            
            [13]: https://oauth2client.readthedocs.io/en/latest/#using-pypy

            
            [14]: https://docs.djangoproject.com/en/1.7/faq/install/#what-python-version-can-i-use-with-django

            
            [15]: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django

            
            [GooglePythonStyle]: https://google.github.io/styleguide/pyguide.html

            
            [GitCommitRules]: http://chris.beams.io/posts/git-commit/#seven-rules
	Contributing
	============

	1. Please sign one of the contributor license agreements [below][6].
	1. [File an issue][9] to notify the maintainers about what you're working on.
	1. [Fork the repo][10], develop and [test][11] your code changes, add docs.
	1. Make sure that your commit messages clearly describe the changes.
	1. [Send][12] a pull request.

	Here are some guidelines for hacking on `oauth2client`.

	Before writing code, file an issue
	----------------------------------

	Use the [issue tracker][7] to start the discussion. It is possible that someone
	else is already working on your idea, your approach is not quite right, or that
	the functionality exists already. The ticket you file in the issue tracker will
	be used to hash that all out.

	Fork `oauth2client`
	-------------------

	We will use GitHub's mechanism for [forking][8] repositories and making pull
	requests. Fork the repository, and make your changes in the forked repository.

	Include tests
	-------------

	Be sure to add the relevant tests before making the pull request. Docs will be
	updated automatically when we merge to `master`, but you should also build
	the docs yourself via `tox -e docs` and make sure they're readable.

	Make the pull request
	---------------------

	Once you have made all your changes, tests, and updated the documentation,
	make a pull request to move everything back into the main `oauth2client`
	repository. Be sure to reference the original issue in the pull request.
	Expect some back-and-forth with regards to style and compliance of these
	rules. In particular:
	* `oauth2client` follows the [Google Python Style Guide][GooglePythonStyle].
	* Follow [these guidelines][GitCommitRules] when authoring your commit message.

	Using a Development Checkout
	----------------------------

	You’ll have to create a development environment to hack on
	`oauth2client`, using a Git checkout:

	- While logged into your GitHub account, navigate to the `oauth2client`
	[repo][1] on GitHub.
	- Fork and clone the `oauth2client` repository to your GitHub account
	by clicking the "Fork" button.
	- Clone your fork of `oauth2client` from your GitHub account to your
	local computer, substituting your account username and specifying
	the destination as `hack-on-oauth2client`. For example:

	```bash
	$ cd ${HOME}
	$ git clone git@github.com:USERNAME/oauth2client.git hack-on-oauth2client
	$ cd hack-on-oauth2client
	$ # Configure remotes such that you can pull changes from the oauth2client
	$ # repository into your local repository.
	$ git remote add upstream https://github.com:google/oauth2client
	$ # fetch and merge changes from upstream into master
	$ git fetch upstream
	$ git merge upstream/master
	```

	Now your local repo is set up such that you will push changes to your
	GitHub repo, from which you can submit a pull request.

	- Create a virtualenv in which to install `oauth2client`:

	```bash
	$ cd ~/hack-on-oauth2client
	$ virtualenv -ppython2.7 env
	```

	Note that very old versions of virtualenv (virtualenv versions
	below, say, 1.10 or thereabouts) require you to pass a
	`--no-site-packages` flag to get a completely isolated environment.

	You can choose which Python version you want to use by passing a
	`-p` flag to `virtualenv`. For example, `virtualenv -ppython2.7`
	chooses the Python 2.7 interpreter to be installed.

	From here on in within these instructions, the
	`~/hack-on-oauth2client/env` virtual environment you created above will be
	referred to as `$VENV`. To use the instructions in the steps that
	follow literally, use the `export VENV=~/hack-on-oauth2client/env`
	command.

	- Install `oauth2client` from the checkout into the virtualenv using
	`setup.py develop`. Running `setup.py develop` must be done while
	the current working directory is the `oauth2client` checkout
	directory:

	```bash
	$ cd ~/hack-on-oauth2client
	$ $VENV/bin/python setup.py develop
	```

	Running Tests
	--------------

	- To run all tests for `oauth2client` on a single Python version, run
	`nosetests` from your development virtualenv (See
	Using a Development Checkout above).

	- To run the full set of `oauth2client` tests on all platforms, install
	[`tox`][2] into a system Python. The `tox` console script will be
	installed into the scripts location for that Python. While in the
	`oauth2client` checkout root directory (it contains `tox.ini`),
	invoke the `tox` console script. This will read the `tox.ini` file and
	execute the tests on multiple Python versions and platforms; while it runs,
	it creates a virtualenv for each version/platform combination. For
	example:

	```bash
	$ sudo pip install tox
	$ cd ~/hack-on-oauth2client
	$ tox
	```

	- In order to run the `pypy` environment (in `tox`) you'll need at
	least version 2.6 of `pypy` installed. See the [docs][13] for
	more information.

	- Note that `django` related tests are turned off for Python 2.6
	and 3.3. This is because `django` dropped support for
	[2.6 in `django==1.7`][14] and for [3.3 in `django==1.9`][15].

	Running System Tests
	--------------------

	- To run system tests you can execute:

	```bash
	$ tox -e system-tests
	$ tox -e system-tests3
	```

	This alone will not run the tests. You'll need to change some local
	auth settings and download some service account configuration files
	from your project to run all the tests.

	- System tests will be run against an actual project and so you'll need to
	provide some environment variables to facilitate this.

	- `OAUTH2CLIENT_TEST_JSON_KEY_PATH`: The path to a service account JSON
	key file; see `tests/data/gcloud/application_default_credentials.json`
	as an example. Such a file can be downloaded directly from the
	developer's console by clicking "Generate new JSON key". See private
	key [docs][3] for more details.
	- `OAUTH2CLIENT_TEST_P12_KEY_PATH`: The path to a service account
	P12/PKCS12 key file. You can download this in the same way as a JSON
	key, just select "P12 Key" as your "Key type" when downloading.
	- `OAUTH2CLIENT_TEST_P12_KEY_EMAIL`: The service account email
	corresponding to the P12/PKCS12 key file.
	- `OAUTH2CLIENT_TEST_USER_KEY_PATH`: The path to a JSON key file for a
	user. If this is not set, the file created by running
	`gcloud auth login` will be used. See
	`tests/data/gcloud/application_default_credentials_authorized_user.json`
	for an example.
	- `OAUTH2CLIENT_TEST_USER_KEY_EMAIL`: The user account email
	corresponding to the user JSON key file.

	- Examples of these can be found in `scripts/local_test_setup.sample`. We
	recommend copying this to `scripts/local_test_setup`, editing the values
	and sourcing them into your environment:

	```bash
	$ source scripts/local_test_setup
	```

	Contributor License Agreements
	------------------------------

	Before we can accept your pull requests you'll need to sign a Contributor
	License Agreement (CLA):

	- If you are an individual writing original source code and **you own
	the intellectual property**, then you'll need to sign an
	[individual CLA][4].
	- **If you work for a company that wants to allow you to contribute your
	work**, then you'll need to sign a [corporate CLA][5].

	You can sign these electronically (just scroll to the bottom). After that,
	we'll be able to accept your pull requests.

	[1]: https://github.com/google/oauth2client
	[2]: https://tox.readthedocs.io/en/latest/
	[3]: https://cloud.google.com/storage/docs/authentication#generating-a-private-key
	[4]: https://developers.google.com/open-source/cla/individual
	[5]: https://developers.google.com/open-source/cla/corporate
	[6]: #contributor-license-agreements
	[7]: https://github.com/google/oauth2client/issues
	[8]: https://help.github.com/articles/fork-a-repo/
	[9]: #before-writing-code-file-an-issue
	[10]: #fork-oauth2client
	[11]: #include-tests
	[12]: #make-the-pull-request
	[13]: https://oauth2client.readthedocs.io/en/latest/#using-pypy
	[14]: https://docs.djangoproject.com/en/1.7/faq/install/#what-python-version-can-i-use-with-django
	[15]: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django
	[GooglePythonStyle]: https://google.github.io/styleguide/pyguide.html
	[GitCommitRules]: http://chris.beams.io/posts/git-commit/#seven-rules