195 lines
6.6 KiB
ReStructuredText
195 lines
6.6 KiB
ReStructuredText
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.
|