Skip to content

CONTRIBUTING.rst

Latest commit

 

History

History
166 lines (105 loc) · 7.08 KB

CONTRIBUTING.rst

File metadata and controls

166 lines (105 loc) · 7.08 KB
Raw

Contributing

  1. Please sign one of the contributor license agreements below.
  2. Fork the repo, develop and test your code changes, add docs.
  3. Make sure that your commit messages clearly describe the changes.
  4. Send a pull request. (Please Read: Faster Pull Request Reviews)

Note: All client libraries are automatically generated using gapic-generator-python. Open source contributions for autogenerated code should be made in gapic-generator-python.

Guidelines for hacking on the Google Cloud Client libraries.

Adding Features

In order to add a feature:

  • The feature must be documented in both the API and narrative documentation.
  • The feature must work fully on all supported Python versions across macOS, Linux, and Windows. (See the package's ``setup.py`` or ``pyproject.toml`` for the definitive list of supported Python versions).
  • The feature must not add unnecessary dependencies (where "unnecessary" is subjective, but new dependencies should be discussed).

Using a Development Checkout

You'll have to create a development environment using a Git checkout:

  • While logged into your GitHub account, navigate to the google-cloud-python repo on GitHub.

  • Fork and clone the google-cloud-python repository to your GitHub account by clicking the "Fork" button.

  • Clone your fork of google-cloud-python from your GitHub account to your local computer, substituting your account username:

    $ cd ${HOME}
$ git clone git@github.com:USERNAME/google-cloud-python.git hack-on-google-cloud-python
$ cd hack-on-google-cloud-python
# Configure remotes such that you can pull changes from the googleapis/google-cloud-python
# repository into your local repository.
$ git remote add upstream git@github.com:googleapis/google-cloud-python.git
# fetch and merge changes from upstream into main
$ git fetch upstream
# merge or rebase depending on your preference
$ git merge upstream/main

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.

To work on the codebase and run the tests, we recommend using nox, but you can also use a virtualenv of your own creation.

Using nox

We use nox to instrument our tests.

  • To test your changes, run unit tests with nox:

    $ nox -s unit

  • To run a single unit test (replace <python_version> with a supported version, e.g., 3.10):

    $ nox -s unit-<python_version> -- -k <name of test>

    Note

    The unit tests and system tests are described in the noxfile.py files in each package directory.

I'm getting weird errors... Can you help?

If the error mentions Python.h not being found, install python-dev and try again. On Debian/Ubuntu:

$ sudo apt-get install python-dev

Coding Style

  • We use automatic code formatters and linters (e.g., black, ruff, pylint) to maintain code quality. Refer to the specific package's noxfile.py for the exact sessions available (e.g., nox -s blacken, nox -s format, or nox -s lint).
  • PEP8 compliance is required, with exceptions defined in the linter configuration of each package.
  • This repository contains configuration for the pre-commit tool, which automates checking our linters during a commit. If you have it installed on your $PATH, you can enable enforcing those checks via:
$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

Exceptions to PEP8:

  • Many unit tests use a helper method, _call_fut ("FUT" is short for "Function-Under-Test"), which is PEP8-incompliant, but more readable. Some also use a local variable, MUT (short for "Module-Under-Test").

Running System Tests

Note

Some packages have highly specific system test requirements or setup steps. Refer to the package's local documentation or comments in noxfile.py if applicable.

Test Coverage

  • The codebase must have 100% test statement coverage after each commit. You can test coverage via nox -s cover.

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.

Build the docs via:

$ nox -s docs

Samples and code snippets

Code samples and snippets live in the samples/ directory of relevant packages. Feel free to provide more examples, but make sure to write tests for those examples. Each folder containing example code requires its own noxfile.py script which automates testing.

The tests will run against a real Google Cloud Project, so you should configure them just like the System Tests.

Versioning

This library follows Semantic Versioning.

Some packages are 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.
  • If you work for a company that wants to allow you to contribute your work, then you'll need to sign a corporate CLA.

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