1Contributing
2============
3
4#. **Please sign one of the contributor license agreements below.**
5#. Fork the repo, develop and test your code changes, add docs.
6#. Make sure that your commit messages clearly describe the changes.
7#. Send a pull request.
8
9Here are some guidelines for hacking on ``google-auth-library-python``.
10
11Making changes
12--------------
13
14A few notes on making changes to ``google-auth-library-python``.
15
16- If you've added a new feature or modified an existing feature, be sure to
17  add or update any applicable documentation in docstrings and in the
18  documentation (in ``docs/``). You can re-generate the reference documentation
19  using ``nox -s docgen``.
20
21- The change must work fully on the following CPython versions:
22  3.6, 3.7, 3.8, 3.9, 3.10 across macOS, Linux, and Windows.
23
24- The codebase *must* have 100% test statement coverage after each commit.
25  You can test coverage via ``nox -e cover``.
26
27Testing changes
28---------------
29
30To test your changes, run unit tests with ``nox``::
31
32    $ nox -s unit
33
34
35Running system tests
36--------------------
37
38You can run the system tests with ``nox``::
39
40    $ nox -f system_tests/noxfile.py
41
42To run a single session, specify it with ``nox -s``::
43
44    $ nox -f system_tests/noxfile.py -s service_account
45
46First, set the environment variable ``GOOGLE_APPLICATION_CREDENTIALS`` to a valid service account.
47See `Creating and Managing Service Account Keys`_ for how to obtain a service account.
48
49Project and Credentials Setup
50-------------------------------
51
52Enable the IAM Service Account Credentials API on the project.
53
54To run system tests locally, you will need to set up a data directory ::
55
56    $ mkdir system_tests/data
57
58Your directory should look like this. Follow the instructions below for creating each file. ::
59
60  system_tests/
61      data/
62        authorized_user.json
63        impersonated_service_account.json
64        service_account.json
65
66
67``authorized_user.json``
68~~~~~~~~~~~~~~~~~~~~~~~~
69
70Use the `gcloud CLI`_ to get an authorized user file ::
71
72    $ gcloud auth application-default login --scopes=https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/cloud-platform,openid
73
74You will see something like::
75
76    Credentials saved to file: [/usr/local/home/.config/gcloud/application_default_credentials.json]
77
78Copy the contents of the file to ``authorized_user.json``.
79
80Open the IAM page of the Google Cloud Console. Grant the user the `Service Account Token Creator Role`.
81This will allow the user to impersonate service accounts on the project.
82
83.. _gcloud CLI: https://cloud.google.com/sdk/gcloud/
84
85
86``service_account.json``
87~~~~~~~~~~~~~~~~~~~~~~~~
88
89Follow `Creating and Managing Service Account Keys`_ to create a service account.
90
91Copy the credentials file to ``service_account.json``.
92
93Grant the account associated with ``service_account.json`` the following roles.
94
95- App Engine Admin (for App Engine tests)
96- Service Account Token Creator (for impersonated credentials and workload identity federation tests)
97- Pub/Sub Viewer (for gRPC tests)
98- Storage Object Viewer (for impersonated credentials tests)
99- DNS Viewer (for workload identity federation tests)
100- GCE Storage Bucket Admin (for downscoping tests)
101
102``impersonated_service_account.json``
103~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104
105Follow `Creating and Managing Service Account Keys`_ to create a service account.
106
107Copy the credentials file to ``impersonated_service_account.json``.
108
109.. _Creating and Managing Service Account Keys: https://cloud.google.com/iam/docs/creating-managing-service-account-keys
110
111``setup_external_accounts``
112~~~~~~~~~~~~~~~~
113
114In order to run the workload identity federation tests, you will need to set up
115a Workload Identity Pool, as well as attach relevant policy bindings for this
116new resource to our service account. To do this, make sure you have IAM Workload
117Identity Pool Admin and Security Admin permissions, and then run:
118
119  $ ./scripts/setup_external_accounts.sh
120
121and then use the output to replace the variables near
122the top of system_tests/system_tests_sync/test_external_accounts.py
123
124App Engine System Tests
125~~~~~~~~~~~~~~~~~~~~~~~~
126
127To run the App Engine tests, you wil need to deploy a default App Engine service.
128If you already have a default service associated with your project, you can skip this step.
129
130Edit ``app.yaml`` so ``service`` is ``default`` instead of ``google-auth-system-tests``.
131From ``system_tests/app_engine_test_app`` run the following commands ::
132
133    $ pip install --target lib -r requirements.txt
134    $ gcloud app deploy -q app.yaml
135
136After the app is deployed, change ``service`` in ``app.yaml`` back to ``google-auth-system-tests``.
137You can now run the App Engine tests: ::
138
139    $ nox -f system_tests/noxfile.py -s app_engine
140
141Compute Engine Tests
142^^^^^^^^^^^^^^^^^^^^
143
144These tests cannot be run locally and will be skipped if they are run outside of Google Compute Engine.
145
146grpc Tests
147^^^^^^^^^^^^
148
149These tests use the Pub/Sub API. Grant the service account specified by `GOOGLE_APPLICATION_CREDENTIALS`
150permissions to list topics. The service account should have at least `roles/pubsub.viewer`.
151
152Coding Style
153------------
154
155This library is PEP8 & Pylint compliant. Our Pylint config is defined at
156``pylintrc`` for package code and ``pylintrc.tests`` for test code. Use
157``nox`` to check for non-compliant code::
158
159   $ nox -s lint
160
161Documentation Coverage and Building HTML Documentation
162------------------------------------------------------
163
164If you fix a bug, and the bug requires an API or behavior modification, all
165documentation in this package which references that API or behavior must be
166changed to reflect the bug fix, ideally in the same commit that fixes the bug
167or adds the feature.
168
169To build and review docs use  ``nox``::
170
171   $ nox -s docs
172
173The HTML version of the docs will be built in ``docs/_build/html``
174
175Versioning
176----------
177
178This library follows `Semantic Versioning`_.
179
180.. _Semantic Versioning: http://semver.org/
181
182It is currently in major version zero (``0.y.z``), which means that anything
183may change at any time and the public API should not be considered
184stable.
185
186Contributor License Agreements
187------------------------------
188
189Before we can accept your pull requests you'll need to sign a Contributor License Agreement (CLA):
190
191- **If you are an individual writing original source code** and **you own the intellectual property**, then you'll need to sign an `individual CLA <https://developers.google.com/open-source/cla/individual>`__.
192- **If you work for a company that wants to allow you to contribute your work**, then you'll need to sign a `corporate CLA <https://developers.google.com/open-source/cla/corporate>`__.
193
194You can sign these electronically (just scroll to the bottom). After that, we'll be able to accept your pull requests.
195