CONTRIBUTING.rst

Contributing to gcloud-aio

Thanks for contributing to gcloud-aio! We appreciate contributions of any size and hope to make it easy for you to dive in. Here's the thousand-foot overview of how we've set this project up.

Local Development

All local development is done via poetry. For any subproject, you can install the development environment with:

cd <project>/
poetry install

And run tests with:

poetry run pytest  # run all tests
poetry run pytest tests/unit  # unit tests only
poetry run pytest tests/integration  # integration tests only

aio and rest

gcloud-aio-* and gcloud-rest-* are in a shared codebase; the later is autogenerated from the former in CI or via the bin/build-rest script. You may need to keep this in mind while developing; all code will need to be generateable into both module trees and runnable without asyncio (though there are some conversion scripts we run to make things a bit more ergonomic -- you're generally safe to write standard asyncio code and rely on the conversion script). Feel free to ping a maintainer if you're having issues with this!

To build and test against the gcloud-rest projects, you can run:

./bin/build-rest

cd build/<project>/
# run the above install & test commands as per normal

Note that if you want modify anything in a pyproject.toml file, running the bin/build-rest script and committing the resulting changes (ie. to the pyproject.rest.toml file) is essential! This must be done after having run the normal poetry lock / poetry update / etc command.

Submitting Changes

Please send us a Pull Request with a clear list of what you've done. When you submit a PR, we'd appreciate test coverage of your changes (and feel free to test other things; we could always use more and better tests!).

Please make sure all tests pass and your commits are atomic (one feature per commit).

Always write a clear message for your changes. We think the conventional changelog message format is pretty cool and try to stick to it as best we can (we even generate release notes from it automatically!).

Roughly speaking, we'd appreciate if your commits looked list this:

feat(taskqueue): implemented task queue manager

Created gcloud.aio.taskqueue.TaskManager for an abstraction layer around
renewing leases on pull-queue tasks. Handles auto-renewal and async
processing.

The first line is the most specific in this format, it should have the format type(project): message, where:

• type is one of feat, fix, docs, refactor, style, perf, test, or chore - project is auth, bigquery, datastore, etc.
• message is a concise description of the patch and brings the line to no more than 72 characters

PR Tests

Note that some integration tests require authentication with Google. Since we don't want to expose our private keys to the world, this means your PR tests might fail for that subset of test cases when you submit your changes.

Long-term, we'd like to switch all such integration tests to using Google emulators and would appreciate any help in getting us closer to that goal! Note that unfortunately Google has not yet release emulators for all the features we have under test, so we'll not yet be able to entirely eliminate this problem.

In the meantime, we are able to manually trigger integration tests for you on any specific commit. Please feel free to add a comment requesting we do so!

Coding Conventions

We use pre-commit to manage our coding conventions and linting. You can install it with pip install pre-commit and set it to run pre-commit hooks for gcloud-aio by running pre-commit install. The same linters get run in CI against all changesets.

You can also run pre-commit in an ad-hoc fashion by calling pre-commit run --all-files.

Other than the above enforced standards, we like code that is easy-to-read for any new or returning contributors with relevant comments where appropriate.

Releases

If you are a maintainer looking to release a new version, see our release documentation.

Thanks for your contribution!

With love, Vi Engineering