| Contributing | |
| ============ | |
| #. **Please sign one of the contributor license agreements below.** | |
| #. Fork the repo, develop and test your code changes, add docs. | |
| #. Make sure that your commit messages clearly describe the changes. | |
| #. Send a pull request. | |
| Here are some guidelines for hacking on ``google-auth-library-python``. | |
| Making changes | |
| -------------- | |
| A few notes on making changes to ``google-auth-library-python``. | |
| - If you've added a new feature or modified an existing feature, be sure to | |
| add or update any applicable documentation in docstrings and in the | |
| documentation (in ``docs/``). You can re-generate the reference documentation | |
| using ``nox -s docgen``. | |
| - The change must work fully on the following CPython versions: | |
| 3.6, 3.7, 3.8, 3.9, 3.10 across macOS, Linux, and Windows. | |
| - The codebase *must* have 100% test statement coverage after each commit. | |
| You can test coverage via ``nox -e cover``. | |
| Testing changes | |
| --------------- | |
| To test your changes, run unit tests with ``nox``:: | |
| $ nox -s unit | |
| Running system tests | |
| -------------------- | |
| You can run the system tests with ``nox``:: | |
| $ nox -f system_tests/noxfile.py | |
| To run a single session, specify it with ``nox -s``:: | |
| $ nox -f system_tests/noxfile.py -s service_account | |
| First, set the environment variable ``GOOGLE_APPLICATION_CREDENTIALS`` to a valid service account. | |
| See `Creating and Managing Service Account Keys`_ for how to obtain a service account. | |
| Project and Credentials Setup | |
| ------------------------------- | |
| Enable the IAM Service Account Credentials API on the project. | |
| To run system tests locally, you will need to set up a data directory :: | |
| $ mkdir system_tests/data | |
| Your directory should look like this. Follow the instructions below for creating each file. :: | |
| system_tests/ | |
| data/ | |
| authorized_user.json | |
| impersonated_service_account.json | |
| service_account.json | |
| ``authorized_user.json`` | |
| ~~~~~~~~~~~~~~~~~~~~~~~~ | |
| Use the `gcloud CLI`_ to get an authorized user file :: | |
| $ gcloud auth application-default login --scopes=https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/cloud-platform,openid | |
| You will see something like:: | |
| Credentials saved to file: [/usr/local/home/.config/gcloud/application_default_credentials.json] | |
| Copy the contents of the file to ``authorized_user.json``. | |
| Open the IAM page of the Google Cloud Console. Grant the user the `Service Account Token Creator Role`. | |
| This will allow the user to impersonate service accounts on the project. | |
| .. _gcloud CLI: https://cloud.google.com/sdk/gcloud/ | |
| ``service_account.json`` | |
| ~~~~~~~~~~~~~~~~~~~~~~~~ | |
| Follow `Creating and Managing Service Account Keys`_ to create a service account. | |
| Copy the credentials file to ``service_account.json``. | |
| Grant the account associated with ``service_account.json`` the following roles. | |
| - App Engine Admin (for App Engine tests) | |
| - Service Account Token Creator (for impersonated credentials and workload identity federation tests) | |
| - Pub/Sub Viewer (for gRPC tests) | |
| - Storage Object Viewer (for impersonated credentials tests) | |
| - DNS Viewer (for workload identity federation tests) | |
| - GCE Storage Bucket Admin (for downscoping tests) | |
| ``impersonated_service_account.json`` | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| Follow `Creating and Managing Service Account Keys`_ to create a service account. | |
| Copy the credentials file to ``impersonated_service_account.json``. | |
| .. _Creating and Managing Service Account Keys: https://cloud.google.com/iam/docs/creating-managing-service-account-keys | |
| ``setup_external_accounts`` | |
| ~~~~~~~~~~~~~~~~ | |
| In order to run the workload identity federation tests, you will need to set up | |
| a Workload Identity Pool, as well as attach relevant policy bindings for this | |
| new resource to our service account. To do this, make sure you have IAM Workload | |
| Identity Pool Admin and Security Admin permissions, and then run: | |
| $ ./scripts/setup_external_accounts.sh | |
| and then use the output to replace the variables near | |
| the top of system_tests/system_tests_sync/test_external_accounts.py | |
| App Engine System Tests | |
| ~~~~~~~~~~~~~~~~~~~~~~~~ | |
| To run the App Engine tests, you wil need to deploy a default App Engine service. | |
| If you already have a default service associated with your project, you can skip this step. | |
| Edit ``app.yaml`` so ``service`` is ``default`` instead of ``google-auth-system-tests``. | |
| From ``system_tests/app_engine_test_app`` run the following commands :: | |
| $ pip install --target lib -r requirements.txt | |
| $ gcloud app deploy -q app.yaml | |
| After the app is deployed, change ``service`` in ``app.yaml`` back to ``google-auth-system-tests``. | |
| You can now run the App Engine tests: :: | |
| $ nox -f system_tests/noxfile.py -s app_engine | |
| Compute Engine Tests | |
| ^^^^^^^^^^^^^^^^^^^^ | |
| These tests cannot be run locally and will be skipped if they are run outside of Google Compute Engine. | |
| grpc Tests | |
| ^^^^^^^^^^^^ | |
| These tests use the Pub/Sub API. Grant the service account specified by `GOOGLE_APPLICATION_CREDENTIALS` | |
| permissions to list topics. The service account should have at least `roles/pubsub.viewer`. | |
| Coding Style | |
| ------------ | |
| This library is PEP8 & Pylint compliant. Our Pylint config is defined at | |
| ``pylintrc`` for package code and ``pylintrc.tests`` for test code. Use | |
| ``nox`` to check for non-compliant code:: | |
| $ nox -s lint | |
| Documentation Coverage and Building HTML Documentation | |
| ------------------------------------------------------ | |
| If you fix a bug, and the bug requires an API or behavior modification, all | |
| documentation in this package which references that API or behavior must be | |
| changed to reflect the bug fix, ideally in the same commit that fixes the bug | |
| or adds the feature. | |
| To build and review docs use ``nox``:: | |
| $ nox -s docs | |
| The HTML version of the docs will be built in ``docs/_build/html`` | |
| Versioning | |
| ---------- | |
| This library follows `Semantic Versioning`_. | |
| .. _Semantic Versioning: http://semver.org/ | |
| It is currently in major version zero (``0.y.z``), which means that anything | |
| may change at any time and the public API should not be considered | |
| stable. | |
| 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 <https://developers.google.com/open-source/cla/individual>`__. | |
| - **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>`__. | |
| You can sign these electronically (just scroll to the bottom). After that, we'll be able to accept your pull requests. |