diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index fb899dd1150e..9c7fe359c743 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -12,20 +12,155 @@ Contributing .. _gapic-generator-python: https://github.com/googleapis/gapic-generator-python .. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +.. contents:: 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. + +.. _repo: https://github.com/googleapis/google-cloud-python + +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 `` with a supported version, e.g., ``3.10``):: + + $ nox -s unit- -- -k + + .. note:: + + The unit tests and system tests are described in the ``noxfile.py`` files in each package directory. + +.. _nox: https://pypi.org/project/nox/ + +***************************************** +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: + +.. code-block:: bash + + $ 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 +******************** + +- To run system tests, you can execute:: + + # Run all system tests + $ nox -s system + +- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. + +.. 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`_. + +.. _Semantic Versioning: http://semver.org/ + +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): +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 `__. +- **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. +You can sign these electronically (just scroll to the bottom). After that, we'll be able to accept your pull requests. diff --git a/packages/bigframes/CONTRIBUTING.rst b/packages/bigframes/CONTRIBUTING.rst index ba8400eb866c..081710ba3937 100644 --- a/packages/bigframes/CONTRIBUTING.rst +++ b/packages/bigframes/CONTRIBUTING.rst @@ -1,160 +1,19 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 - ``python-bigquery-dataframes`` `repo`_ on GitHub. - -- Fork and clone the ``python-bigquery-dataframes`` repository to your GitHub account by - clicking the "Fork" button. - -- Clone your fork of ``python-bigquery-dataframes`` from your GitHub account to your local - computer, substituting your account username and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python/tree/main/packages/bigframes - -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:: - - $ nox -s unit-3.14 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``format``. This will eliminate many lint errors. Run via:: - - $ nox -s format - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``python-bigquery-dataframes``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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"). +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. ******************** Running System Tests ******************** -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.14 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.10, 3.12 and 3.14. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - - System tests will be run against an actual project. A project can be set in the environment variable ``$GOOGLE_CLOUD_PROJECT``. If not, the project property set in the `Google Cloud CLI `__ @@ -191,118 +50,3 @@ Running System Tests - ``serviceusage.services.enable`` - ``bigquery.connections.create`` - ``resourcemanager.projects.setIamPolicy`` - -- You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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/` catalogue. 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. If you decide to create a new folder, you can -base it on the `samples/snippets` folder (providing `noxfile.py` and -the requirements files). - -The tests will run against a real Google Cloud Project, so you should -configure them just like the System Tests. - -- To run sample tests, you can execute:: - - # Run all tests in a folder - $ cd samples/snippets - $ nox -s py-3.10 - - # Run a single sample test - $ cd samples/snippets - $ nox -s py-3.10 -- -k - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/packages/bigframes/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/bigframes - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/packages/bigframes/noxfile.py - - - - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. diff --git a/packages/bigquery-magics/CONTRIBUTING.md b/packages/bigquery-magics/CONTRIBUTING.md deleted file mode 100644 index 6272489dae31..000000000000 --- a/packages/bigquery-magics/CONTRIBUTING.md +++ /dev/null @@ -1,28 +0,0 @@ -# How to Contribute - -We'd love to accept your patches and contributions to this project. There are -just a few small guidelines you need to follow. - -## Contributor License Agreement - -Contributions to this project must be accompanied by a Contributor License -Agreement. You (or your employer) retain the copyright to your contribution; -this simply gives us permission to use and redistribute your contributions as -part of the project. Head over to to see -your current agreements on file or to sign a new one. - -You generally only need to submit a CLA once, so if you've already submitted one -(even if it was for a different project), you probably don't need to do it -again. - -## Code Reviews - -All submissions, including submissions by project members, require review. We -use GitHub pull requests for this purpose. Consult -[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more -information on using pull requests. - -## Community Guidelines - -This project follows [Google's Open Source Community -Guidelines](https://opensource.google/conduct/). diff --git a/packages/bigquery-magics/CONTRIBUTING.rst b/packages/bigquery-magics/CONTRIBUTING.rst index 07e9be8098d7..4d6e87dd6421 100644 --- a/packages/bigquery-magics/CONTRIBUTING.rst +++ b/packages/bigquery-magics/CONTRIBUTING.rst @@ -1,256 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 - ``python-bigquery-magics`` `repo`_ on GitHub. - -- Fork and clone the ``python-bigquery-magics`` repository to your GitHub account by - clicking the "Fork" button. - -- Clone your fork of ``python-bigquery-magics`` from your GitHub account to your local - computer, substituting your account username and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python/tree/main/packages/bigquery-magics - -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:: - - $ nox -s unit-3.13 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``python-bigquery-magics``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.13 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.9, 3.11, 3.12 and 3.13. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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 - - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/packages/bigquery-magics/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/bigquery-magics - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/packages/bigquery-magics/noxfile.py - - -We also explicitly decided to support Python 3 beginning with version 3.9. -Reasons for this include: - -- Encouraging use of newest versions of Python 3 -- Taking the lead of `prominent`_ open-source `projects`_ -- `Unicode literal support`_ which allows for a cleaner codebase that - works in both Python 2 and Python 3 - -.. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django -.. _projects: http://flask.pocoo.org/docs/0.10/python3/ -.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/ - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/db-dtypes/CONTRIBUTING.rst b/packages/db-dtypes/CONTRIBUTING.rst index 73ca9ecd04de..4d6e87dd6421 100644 --- a/packages/db-dtypes/CONTRIBUTING.rst +++ b/packages/db-dtypes/CONTRIBUTING.rst @@ -1,247 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 - ``python-db-dtypes-pandas`` `repo`_ on GitHub. - -- Fork and clone the ``python-db-dtypes-pandas`` repository to your GitHub account by - clicking the "Fork" button. - -- Clone your fork of ``python-db-dtypes-pandas`` from your GitHub account to your local - computer, substituting your account username and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python/tree/main/packages/db-dtypes - -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:: - - $ nox -s unit-3.14 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``python-db-dtypes-pandas``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.12 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.12. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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 - - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/packages/db-dtypes/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/db-dtypes - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/packages/db-dtypes/noxfile.py - - - - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/django-google-spanner/CONTRIBUTING.md b/packages/django-google-spanner/CONTRIBUTING.md deleted file mode 100644 index 2b19390a48ef..000000000000 --- a/packages/django-google-spanner/CONTRIBUTING.md +++ /dev/null @@ -1,25 +0,0 @@ -# How to Contribute - -## Contributor License Agreement - -Contributions to this project must be accompanied by a Contributor License -Agreement. You (or your employer) retain the copyright to your contribution; -this simply gives us permission to use and redistribute your contributions as -part of the project. Head over to to see -your current agreements on file or to sign a new one. - -You generally only need to submit a CLA once, so if you've already submitted one -(even if it was for a different project), you probably don't need to do it -again. - -## Code reviews - -All submissions, including submissions by project members, require review. We -use GitHub pull requests for this purpose. Consult -[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more -information on using pull requests. - -## Community Guidelines - -This project follows [Google's Open Source Community -Guidelines](https://opensource.google/conduct/). diff --git a/packages/django-google-spanner/CONTRIBUTING.rst b/packages/django-google-spanner/CONTRIBUTING.rst new file mode 100644 index 000000000000..4d6e87dd6421 --- /dev/null +++ b/packages/django-google-spanner/CONTRIBUTING.rst @@ -0,0 +1,11 @@ +############ +Contributing +############ + +This package is part of the ``google-cloud-python`` monorepo. + +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. + +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst + +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/gapic-generator/CONTRIBUTING.rst b/packages/gapic-generator/CONTRIBUTING.rst new file mode 100644 index 000000000000..4d6e87dd6421 --- /dev/null +++ b/packages/gapic-generator/CONTRIBUTING.rst @@ -0,0 +1,11 @@ +############ +Contributing +############ + +This package is part of the ``google-cloud-python`` monorepo. + +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. + +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst + +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/gcp-sphinx-docfx-yaml/CONTRIBUTING.md b/packages/gcp-sphinx-docfx-yaml/CONTRIBUTING.md deleted file mode 100644 index 1237ad35d3f8..000000000000 --- a/packages/gcp-sphinx-docfx-yaml/CONTRIBUTING.md +++ /dev/null @@ -1,34 +0,0 @@ -**Please note that this is the forked version of the original repository, which -is found on https://github.com/docascode/sphinx-docfx-yaml. Unless the issue -applies only to this repository, please also file an issue and/or contribute -to the original repository as well.** - -# How to Contribute - -We'd love to accept your patches and contributions to this project. -There are just a few small guidelines you need to follow. - -## Contributor License Agreement - -Contributions to this project must be accompanied by a Contributor License -Agreement (CLA). You (or your employer) retain the copyright to your -contribution; this simply gives us permission to use and redistribute your -contributions as part of the project. Head over to - to see your current agreements on file or -to sign a new one. - -You generally only need to submit a CLA once, so if you've already submitted one -(even if it was for a different project), you probably don't need to do it -again. - -## Code Reviews - -All submissions, including submissions by project members, require review. We -use GitHub pull requests for this purpose. Consult -[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more -information on using pull requests. - -## Community Guidelines - -This project follows -[Google's Open Source Community Guidelines](https://opensource.google/conduct/). diff --git a/packages/gcp-sphinx-docfx-yaml/CONTRIBUTING.rst b/packages/gcp-sphinx-docfx-yaml/CONTRIBUTING.rst new file mode 100644 index 000000000000..e822b8045be2 --- /dev/null +++ b/packages/gcp-sphinx-docfx-yaml/CONTRIBUTING.rst @@ -0,0 +1,14 @@ +############ +Contributing +############ + +This package is part of the ``google-cloud-python`` monorepo. + +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. + +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst + +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. + +.. note:: + This is the forked version of the original repository, which is found on https://github.com/docascode/sphinx-docfx-yaml. Unless the issue applies only to this repository, please also file an issue and/or contribute to the original repository as well. diff --git a/packages/google-api-core/CONTRIBUTING.rst b/packages/google-api-core/CONTRIBUTING.rst index d6250b839447..4d6e87dd6421 100644 --- a/packages/google-api-core/CONTRIBUTING.rst +++ b/packages/google-api-core/CONTRIBUTING.rst @@ -2,244 +2,10 @@ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python - -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:: - - $ nox -s unit-3.13 -- -k - - - .. note:: - - The unit tests tests are described in the ``noxfile.py`` files - in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``google-cloud-python``. The the suggested remote name ``upstream`` - should point to the official ``googleapis`` checkout and the - the branch should be the main branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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"). - - -************* -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/` catalogue. 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. If you decide to create a new folder, you can -base it on the `samples/snippets` folder (providing `noxfile.py` and -the requirements files). - -The tests will run against a real Google Cloud Project, so you should -configure them just like the System Tests. - -- To run sample tests, you can execute:: - - # Run all tests in a folder - $ cd samples/snippets - $ nox -s py-3.10 - - # Run a single sample test - $ cd samples/snippets - $ nox -s py-3.10 -- -k - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-api-core - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/noxfile.py - - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-auth-httplib2/CONTRIBUTING.rst b/packages/google-auth-httplib2/CONTRIBUTING.rst new file mode 100644 index 000000000000..4d6e87dd6421 --- /dev/null +++ b/packages/google-auth-httplib2/CONTRIBUTING.rst @@ -0,0 +1,11 @@ +############ +Contributing +############ + +This package is part of the ``google-cloud-python`` monorepo. + +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. + +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst + +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-auth-oauthlib/CONTRIBUTING.rst b/packages/google-auth-oauthlib/CONTRIBUTING.rst index b014785be18b..4d6e87dd6421 100644 --- a/packages/google-auth-oauthlib/CONTRIBUTING.rst +++ b/packages/google-auth-oauthlib/CONTRIBUTING.rst @@ -1,257 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python - -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:: - - $ nox -s unit-3.14 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``google-cloud-python``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.12 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.12. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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 - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-auth-oauthlib - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/noxfile.py - - -We also explicitly decided to support Python 3 beginning with version 3.10. -Reasons for this include: - -- Encouraging use of newest versions of Python 3 -- Taking the lead of `prominent`_ open-source `projects`_ -- `Unicode literal support`_ which allows for a cleaner codebase that - works in both Python 2 and Python 3 - -.. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django -.. _projects: http://flask.pocoo.org/docs/0.10/python3/ -.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/ - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-auth-oauthlib/docs/index.rst b/packages/google-auth-oauthlib/docs/index.rst index 313b0590ef7f..3cb133c306b9 100644 --- a/packages/google-auth-oauthlib/docs/index.rst +++ b/packages/google-auth-oauthlib/docs/index.rst @@ -39,12 +39,3 @@ For more details, see `LICENSE`_ .. _LICENSE: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-auth-oauthlib/LICENSE - -Contributing ------------- - -We happily welcome contributions, please see our `contributing`_ documentation -for details. - -.. _contributing: - https://github.com/GoogleCloudPlatform/google-auth-library-python/CONTRIBUTING.rst diff --git a/packages/google-auth/CONTRIBUTING.rst b/packages/google-auth/CONTRIBUTING.rst index ad58d7896233..a1e8102b0571 100644 --- a/packages/google-auth/CONTRIBUTING.rst +++ b/packages/google-auth/CONTRIBUTING.rst @@ -1,39 +1,18 @@ +############ 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. +This package is part of the ``google-cloud-python`` monorepo. -Here are some guidelines for hacking on ``google-auth-library-python``. +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -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 docs``. - -- The change must work fully on the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 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 +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. +********************* Running system tests --------------------- +********************* You can run the system tests with ``nox``:: @@ -148,47 +127,3 @@ 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 `__. -- **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. diff --git a/packages/google-auth/docs/index.rst b/packages/google-auth/docs/index.rst index 8a5f13a6daf4..a825c686fd35 100644 --- a/packages/google-auth/docs/index.rst +++ b/packages/google-auth/docs/index.rst @@ -63,12 +63,3 @@ details, see `LICENSE`_ .. _LICENSE: https://github.com/GoogleCloudPlatform/google-auth-library-python/blob/main/LICENSE - -Contributing ------------- - -We happily welcome contributions, please see our `contributing`_ documentation -for details. - -.. _contributing: - https://github.com/GoogleCloudPlatform/google-auth-library-python/blob/main/CONTRIBUTING.rst diff --git a/packages/google-cloud-bigquery-storage/CONTRIBUTING.rst b/packages/google-cloud-bigquery-storage/CONTRIBUTING.rst index 17b815249f0a..4d6e87dd6421 100644 --- a/packages/google-cloud-bigquery-storage/CONTRIBUTING.rst +++ b/packages/google-cloud-bigquery-storage/CONTRIBUTING.rst @@ -1,285 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.7, 3.8, 3.9, 3.10, 3.11, 3.12 and 3.13 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 - ``python-bigquery-storage`` `repo`_ on GitHub. - -- Fork and clone the ``python-bigquery-storage`` repository to your GitHub account by - clicking the "Fork" button. - -- Clone your fork of ``python-bigquery-storage`` from your GitHub account to your local - computer, substituting your account username and specifying the destination - as ``hack-on-python-bigquery-storage``. E.g.:: - - $ cd ${HOME} - $ git clone git@github.com:USERNAME/python-bigquery-storage.git hack-on-python-bigquery-storage - $ cd hack-on-python-bigquery-storage - # Configure remotes such that you can pull changes from the googleapis/python-bigquery-storage - # repository into your local repository. - $ git remote add upstream git@github.com:googleapis/python-bigquery-storage.git - # fetch and merge changes from upstream into main - $ git fetch upstream - $ 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. - -.. _repo: https://github.com/googleapis/python-bigquery-storage - -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:: - - $ nox -s unit-3.13 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``python-bigquery-storage``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.8 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.8. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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/` catalogue. 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. If you decide to create a new folder, you can -base it on the `samples/snippets` folder (providing `noxfile.py` and -the requirements files). - -The tests will run against a real Google Cloud Project, so you should -configure them just like the System Tests. - -- To run sample tests, you can execute:: - - # Run all tests in a folder - $ cd samples/snippets - $ nox -s py-3.8 - - # Run a single sample test - $ cd samples/snippets - $ nox -s py-3.8 -- -k - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/python-bigquery-storage/blob/main/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud-bigquery-storage - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.7`_ -- `Python 3.8`_ -- `Python 3.9`_ -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ - -.. _Python 3.7: https://docs.python.org/3.7/ -.. _Python 3.8: https://docs.python.org/3.8/ -.. _Python 3.9: https://docs.python.org/3.9/ -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/python-bigquery-storage/blob/main/noxfile.py - - -We also explicitly decided to support Python 3 beginning with version 3.7. -Reasons for this include: - -- Encouraging use of newest versions of Python 3 -- Taking the lead of `prominent`_ open-source `projects`_ -- `Unicode literal support`_ which allows for a cleaner codebase that - works in both Python 2 and Python 3 - -.. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django -.. _projects: http://flask.pocoo.org/docs/0.10/python3/ -.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/ - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-cloud-bigquery/CONTRIBUTING.rst b/packages/google-cloud-bigquery/CONTRIBUTING.rst index c8ee1493cc9e..4d6e87dd6421 100644 --- a/packages/google-cloud-bigquery/CONTRIBUTING.rst +++ b/packages/google-cloud-bigquery/CONTRIBUTING.rst @@ -1,283 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.9, 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 - ``python-bigquery`` `repo`_ on GitHub. - -- Fork and clone the ``python-bigquery`` repository to your GitHub account by - clicking the "Fork" button. - -- Clone your fork of ``python-bigquery`` from your GitHub account to your local - computer, substituting your account username and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-bigquery - -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:: - - $ nox -s unit-3.13 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``python-bigquery``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.13 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.9 and 3.13. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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/` catalogue. 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. If you decide to create a new folder, you can -base it on the `samples/snippets` folder (providing `noxfile.py` and -the requirements files). - -The tests will run against a real Google Cloud Project, so you should -configure them just like the System Tests. - -- To run sample tests, you can execute:: - - # Run all tests in a folder - $ cd samples/snippets - $ nox -s py-3.9 - - # Run a single sample test - $ cd samples/snippets - $ nox -s py-3.9 -- -k - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/packages/google-cloud-bigquery/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud-bigquery - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.9`_ -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.9: https://docs.python.org/3.9/ -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/packages/google-cloud-bigquery/noxfile.py - - -We also explicitly decided to support Python 3 beginning with version 3.9. -Reasons for this include: - -- Encouraging use of newest versions of Python 3 -- Taking the lead of `prominent`_ open-source `projects`_ -- `Unicode literal support`_ which allows for a cleaner codebase that - works in both Python 2 and Python 3 - -.. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django -.. _projects: http://flask.pocoo.org/docs/0.10/python3/ -.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/ - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-cloud-bigtable/CONTRIBUTING.rst b/packages/google-cloud-bigtable/CONTRIBUTING.rst index 9de20daeac72..4d6e87dd6421 100644 --- a/packages/google-cloud-bigtable/CONTRIBUTING.rst +++ b/packages/google-cloud-bigtable/CONTRIBUTING.rst @@ -1,281 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 - ``python-bigtable`` `repo`_ on GitHub. - -- Fork and clone the ``python-bigtable`` repository to your GitHub account by - clicking the "Fork" button. - -- Clone your fork of ``python-bigtable`` from your GitHub account to your local - computer, substituting your account username and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-bigtable - -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:: - - $ nox -s unit-3.14 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``ruff``. You can run it using - the nox session ``format``. This will eliminate many lint errors. Run via:: - - $ nox -s format - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``python-bigtable``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.12 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.12. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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/` catalogue. 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. If you decide to create a new folder, you can -base it on the `samples/snippets` folder (providing `noxfile.py` and -the requirements files). - -The tests will run against a real Google Cloud Project, so you should -configure them just like the System Tests. - -- To run sample tests, you can execute:: - - # Run all tests in a folder - $ cd samples/snippets - $ nox -s py-3.14 - - # Run a single sample test - $ cd samples/snippets - $ nox -s py-3.14 -- -k - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/packages/google-cloud-bigtable/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud-bigtable - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/packages/google-cloud-bigtable/noxfile.py - - -We also explicitly decided to support Python 3 beginning with version 3.10. -Reasons for this include: - -- Encouraging use of newest versions of Python 3 -- Taking the lead of `prominent`_ open-source `projects`_ -- `Unicode literal support`_ which allows for a cleaner codebase that - works in both Python 2 and Python 3 - -.. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django -.. _projects: http://flask.pocoo.org/docs/0.10/python3/ -.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/ - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-cloud-core/CONTRIBUTING.rst b/packages/google-cloud-core/CONTRIBUTING.rst index f4ec66686af0..4d6e87dd6421 100644 --- a/packages/google-cloud-core/CONTRIBUTING.rst +++ b/packages/google-cloud-core/CONTRIBUTING.rst @@ -1,246 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python - -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:: - - $ nox -s unit-3.14 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``google-cloud-python``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.12 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.12. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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 - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud-core - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/noxfile.py - - - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-cloud-datastore/CONTRIBUTING.rst b/packages/google-cloud-datastore/CONTRIBUTING.rst index 58212c11fb20..733e7dd7d251 100644 --- a/packages/google-cloud-datastore/CONTRIBUTING.rst +++ b/packages/google-cloud-datastore/CONTRIBUTING.rst @@ -1,162 +1,19 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python - -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:: - - $ nox -s unit-3.13 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``google-cloud-python``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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"). +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. ******************** Running System Tests ******************** -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.10 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.10. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - - You'll need to create composite `indexes `__ with the ``gcloud`` command line @@ -181,126 +38,3 @@ Running System Tests datastore instance via:: $ python tests/system/utils/clear_datastore.py - -************* -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/` catalogue. 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. If you decide to create a new folder, you can -base it on the `samples/snippets` folder (providing `noxfile.py` and -the requirements files). - -The tests will run against a real Google Cloud Project, so you should -configure them just like the System Tests. - -- To run sample tests, you can execute:: - - # Run all tests in a folder - $ cd samples/snippets - $ nox -s py-3.10 - - # Run a single sample test - $ cd samples/snippets - $ nox -s py-3.10 -- -k - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud-datastore - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/noxfile.py - - -We also explicitly decided to support Python 3 beginning with version 3.10. -Reasons for this include: - -- Encouraging use of newest versions of Python 3 -- Taking the lead of `prominent`_ open-source `projects`_ -- `Unicode literal support`_ which allows for a cleaner codebase that - works in both Python 2 and Python 3 - -.. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django -.. _projects: http://flask.pocoo.org/docs/0.10/python3/ -.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/ - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. diff --git a/packages/google-cloud-dns/CONTRIBUTING.rst b/packages/google-cloud-dns/CONTRIBUTING.rst index 89f0df89dff7..4d6e87dd6421 100644 --- a/packages/google-cloud-dns/CONTRIBUTING.rst +++ b/packages/google-cloud-dns/CONTRIBUTING.rst @@ -1,246 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python - -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:: - - $ nox -s unit-3.14 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``google-cloud-python``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.10 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.10. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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 - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud-dns - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/noxfile.py - - - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-cloud-documentai-toolbox/CONTRIBUTING.rst b/packages/google-cloud-documentai-toolbox/CONTRIBUTING.rst index 0130b1514fd9..4d6e87dd6421 100644 --- a/packages/google-cloud-documentai-toolbox/CONTRIBUTING.rst +++ b/packages/google-cloud-documentai-toolbox/CONTRIBUTING.rst @@ -1,245 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 - ``python-documentai-toolbox`` `repo`_ on GitHub. - -- Fork and clone the ``python-documentai-toolbox`` repository to your GitHub account by - clicking the "Fork" button. - -- Clone your fork of ``python-documentai-toolbox`` from your GitHub account to your local - computer, substituting your account username and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-documentai-toolbox - -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:: - - $ nox -s unit-3.14 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``python-documentai-toolbox``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.14 -- -k - - - .. note:: - - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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 - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/packages/google-cloud-documentai-toolbox/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud-documentai-toolbox - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/packages/google-cloud-documentai-toolbox/noxfile.py - - - - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-cloud-error-reporting/CONTRIBUTING.rst b/packages/google-cloud-error-reporting/CONTRIBUTING.rst index eee3cc425b25..4d6e87dd6421 100644 --- a/packages/google-cloud-error-reporting/CONTRIBUTING.rst +++ b/packages/google-cloud-error-reporting/CONTRIBUTING.rst @@ -1,287 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python - -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:: - - $ nox -s unit-3.13 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``google-cloud-python``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.14 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.14. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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/` catalogue. 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. If you decide to create a new folder, you can -base it on the `samples/snippets` folder (providing `noxfile.py` and -the requirements files). - -The tests will run against a real Google Cloud Project, so you should -configure them just like the System Tests. - -- To run sample tests, you can execute:: - - # Run all tests in a folder - $ cd samples/snippets - $ nox -s py-3.14 - - # Run a single sample test - $ cd samples/snippets - $ nox -s py-3.14 -- -k - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud-error-reporting - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.7`_ -- `Python 3.8`_ -- `Python 3.9`_ -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.7: https://docs.python.org/3.7/ -.. _Python 3.8: https://docs.python.org/3.8/ -.. _Python 3.9: https://docs.python.org/3.9/ -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/noxfile.py - - -We also explicitly decided to support Python 3 beginning with version 3.7. -Reasons for this include: - -- Encouraging use of newest versions of Python 3 -- Taking the lead of `prominent`_ open-source `projects`_ -- `Unicode literal support`_ which allows for a cleaner codebase that - works in both Python 2 and Python 3 - -.. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django -.. _projects: http://flask.pocoo.org/docs/0.10/python3/ -.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/ - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-cloud-firestore/CONTRIBUTING.rst b/packages/google-cloud-firestore/CONTRIBUTING.rst index 4995bd65471e..261ce214fc9f 100644 --- a/packages/google-cloud-firestore/CONTRIBUTING.rst +++ b/packages/google-cloud-firestore/CONTRIBUTING.rst @@ -1,155 +1,14 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python - -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:: - - $ nox -s unit-3.14 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``google-cloud-python``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.14 -- -k - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. ************************** Updating Conformance Tests @@ -160,126 +19,3 @@ The firestore client libraries use a shared set of conformance tests, the source To update the copy of these conformance tests used by this repository, run the provided Makefile: $ make -f Makefile_v1 - -************* -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/` catalogue. 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. If you decide to create a new folder, you can -base it on the `samples/snippets` folder (providing `noxfile.py` and -the requirements files). - -The tests will run against a real Google Cloud Project, so you should -configure them just like the System Tests. - -- To run sample tests, you can execute:: - - # Run all tests in a folder - $ cd samples/snippets - $ nox -s py-3.10 - - # Run a single sample test - $ cd samples/snippets - $ nox -s py-3.10 -- -k - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud-firestore - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/noxfile.py - - -We also explicitly decided to support Python 3 beginning with version 3.10. -Reasons for this include: - -- Encouraging use of newest versions of Python 3 -- Taking the lead of `prominent`_ open-source `projects`_ -- `Unicode literal support`_ which allows for a cleaner codebase that - works in both Python 2 and Python 3 - -.. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django -.. _projects: http://flask.pocoo.org/docs/0.10/python3/ -.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/ - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. diff --git a/packages/google-cloud-logging/CONTRIBUTING.rst b/packages/google-cloud-logging/CONTRIBUTING.rst index 6d5969ff4712..4d6e87dd6421 100644 --- a/packages/google-cloud-logging/CONTRIBUTING.rst +++ b/packages/google-cloud-logging/CONTRIBUTING.rst @@ -1,271 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python - -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:: - - $ nox -s unit-3.14 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``google-cloud-python``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.14 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.14. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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/` catalogue. 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. If you decide to create a new folder, you can -base it on the `samples/snippets` folder (providing `noxfile.py` and -the requirements files). - -The tests will run against a real Google Cloud Project, so you should -configure them just like the System Tests. - -- To run sample tests, you can execute:: - - # Run all tests in a folder - $ cd samples/snippets - $ nox -s py-3.10 - - # Run a single sample test - $ cd samples/snippets - $ nox -s py-3.10 -- -k - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud-logging - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/noxfile.py - - -We also explicitly decided to support Python 3 beginning with version 3.10. - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-cloud-ndb/CONTRIBUTING.rst b/packages/google-cloud-ndb/CONTRIBUTING.rst index ac6ba9eae205..06fd5ad91444 100644 --- a/packages/google-cloud-ndb/CONTRIBUTING.rst +++ b/packages/google-cloud-ndb/CONTRIBUTING.rst @@ -2,181 +2,31 @@ Contributing ############ -#. **Please sign one of the contributor license agreements below.** -#. ``python-ndb`` is undergoing heavy development right now, so if you plan to - implement a feature, please create an issue to discuss your idea first. That - way we can coordinate and avoid possibly duplicating ongoing work. -#. 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on ``python-ndb``. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -Adding Features -*************** +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. -In order to add a feature to ``python-ndb``: - -- The feature must be documented in both the API and narrative - documentation (in ``docs/``). - -- The feature must work fully on the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course subjective, but new dependencies should - be discussed). - -**************************** -Using a Development Checkout -**************************** - -You'll have to create a development environment to hack on -``python-ndb``, using a Git checkout: - -- While logged into your GitHub account, navigate to the - ``python-ndb`` `repo`_ on GitHub. - -- Fork and clone the ``python-ndb`` repository to your GitHub account by - clicking the "Fork" button. - -- Clone your fork of ``python-ndb`` from your GitHub account to your local - computer, substituting your account username and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 python-ndb - # 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-ndb - -Using ``nox`` -============= - -We use `nox `__ to instrument our tests. - -- To test your changes, run unit tests with ``nox``:: - - $ nox -s unit-3.14 - $ ... - -.. nox: https://pypi.org/project/nox-automation/ +********************* +Running Unit Tests +********************* - To run unit tests that use Memcached or Redis, you must have them running and set the appropriate environment variables: $ export MEMCACHED_HOSTS=localhost:11211 $ export REDIS_CACHE_URL=redis://localhost:6379 - -Note on Editable Installs / Develop Mode -======================================== - -- As mentioned previously, using ``setuptools`` in `develop mode`_ - or a ``pip`` `editable install`_ is not possible with this - library. This is because this library uses `namespace packages`_. - For context see `Issue #2316`_ and the relevant `PyPA issue`_. - - Since ``editable`` / ``develop`` mode can't be used, packages - need to be installed directly. Hence your changes to the source - tree don't get incorporated into the **already installed** - package. - -.. _namespace packages: https://www.python.org/dev/peps/pep-0420/ -.. _Issue #2316: https://github.com/googleapis/google-cloud-python/issues/2316 -.. _PyPA issue: https://github.com/pypa/packaging-problems/issues/12 -.. _develop mode: https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode -.. _editable install: https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs - -***************************************** -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 -************ - -- PEP8 compliance, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``python-ndb``. The the suggested remote name ``upstream`` - should point to the official ``googleapis`` checkout and the - the branch should be the main branch on that remote (``main``). - -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 ******************** -- To run system tests for a given package, you can execute:: - - $ export SYSTEM_TESTS_DATABASE=system-tests-named-db - $ nox -e system - - .. note:: - - System tests are only configured to run under Python 3.14. For - expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - - System tests may be run against the emulator. To do this, set the ``DATASTORE_EMULATOR_HOST`` environment variable. Alternatively, system tests with the emulator can run with - `nox -e emulator-system-PYTHON_VERSION` - -- System tests will be run against an actual project and - so you'll need to provide some environment variables to facilitate - authentication to your project: - - - ``GOOGLE_APPLICATION_CREDENTIALS``: The path to a JSON key file; - see ``system_tests/app_credentials.json.sample`` as an example. Such a file - can be downloaded directly from the developer's console by clicking - "Generate new JSON key". See private key - `docs `__ - for more details. - - - In order for Logging system tests to work, the Service Account - will also have to be made a project ``Owner``. This can be changed under - "IAM & Admin". Additionally, ``cloud-logs@google.com`` must be given - ``Editor`` permissions on the project. + ``nox -e emulator-system-PYTHON_VERSION`` - For datastore tests, you'll need to create composite `indexes `__ @@ -195,113 +45,11 @@ Running System Tests $ gcloud datastore indexes create tests/system/index.yaml $ gcloud alpha datastore indexes create --database=$SYSTEM_TESTS_DATABASE tests/system/index.yaml +Note on Editable Installs / Develop Mode +======================================== -************* -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. - -To build and review docs (where ``${VENV}`` refers to the virtualenv you're -using to develop ``python-ndb``): - -#. After following the steps above in "Using a Development Checkout", install - Sphinx and all development requirements in your virtualenv:: - - $ cd ${HOME}/hack-on-google-cloud-python - $ ${VENV}/bin/pip install Sphinx - -#. Change into the ``docs`` directory within your ``python-ndb`` checkout and - execute the ``make`` command with some flags:: - - $ cd ${HOME}/hack-on-google-cloud-python/docs - $ make clean html SPHINXBUILD=${VENV}/bin/sphinx-build - - The ``SPHINXBUILD=...`` argument tells Sphinx to use the virtualenv Python, - which will have both Sphinx and ``python-ndb`` (for API documentation - generation) installed. - -#. Open the ``docs/_build/html/index.html`` file to see the resulting HTML - rendering. - -As an alternative to 1. and 2. above, if you have ``nox`` installed, you -can build the docs via:: - - $ nox -s docs - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/packages/google-cloud-ndb/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud/ - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/packages/google-cloud-ndb/noxfile.py - - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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 `__. +- Using ``setuptools`` in `develop mode`_ or a ``pip`` `editable install`_ is not possible with this library. This is because this library uses `namespace packages`_. -You can sign these electronically (just scroll to the bottom). After that, -we'll be able to accept your pull requests. +.. _namespace packages: https://www.python.org/dev/peps/pep-0420/ +.. _develop mode: https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode +.. _editable install: https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs diff --git a/packages/google-cloud-pubsub/CONTRIBUTING.rst b/packages/google-cloud-pubsub/CONTRIBUTING.rst index 3aff2258e23c..4d6e87dd6421 100644 --- a/packages/google-cloud-pubsub/CONTRIBUTING.rst +++ b/packages/google-cloud-pubsub/CONTRIBUTING.rst @@ -1,269 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 - ``python-pubsub`` `repo`_ on GitHub. - -- Fork and clone the ``python-pubsub`` repository to your GitHub account by - clicking the "Fork" button. - -- Clone your fork of ``python-pubsub`` from your GitHub account to your local - computer, substituting your account username and specifying the destination - as ``hack-on-python-pubsub``. E.g.:: - - $ cd ${HOME} - $ git clone git@github.com:USERNAME/python-pubsub.git hack-on-python-pubsub - $ cd hack-on-python-pubsub - # Configure remotes such that you can pull changes from the googleapis/python-pubsub - # repository into your local repository. - $ git remote add upstream git@github.com:googleapis/python-pubsub.git - # fetch and merge changes from upstream into main - $ git fetch upstream - $ 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. - -.. _repo: https://github.com/googleapis/python-pubsub - -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:: - - $ nox -s unit-3.13 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``python-pubsub``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.12 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.12. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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/` catalogue. 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. If you decide to create a new folder, you can -base it on the `samples/snippets` folder (providing `noxfile.py` and -the requirements files). - -The tests will run against a real Google Cloud Project, so you should -configure them just like the System Tests. - -- To run sample tests, you can execute:: - - # Run all tests in a folder - $ cd samples/snippets - $ nox -s py-3.14 - - # Run a single sample test - $ cd samples/snippets - $ nox -s py-3.14 -- -k - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/python-pubsub/blob/main/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud-pubsub - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/python-pubsub/blob/main/noxfile.py - - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-cloud-runtimeconfig/CONTRIBUTING.rst b/packages/google-cloud-runtimeconfig/CONTRIBUTING.rst index a971f5b5ffb4..4d6e87dd6421 100644 --- a/packages/google-cloud-runtimeconfig/CONTRIBUTING.rst +++ b/packages/google-cloud-runtimeconfig/CONTRIBUTING.rst @@ -1,257 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python - -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:: - - $ nox -s unit-3.13 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``google-cloud-python``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.12 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.12. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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 - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud-runtimeconfig - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/noxfile.py - - -We also explicitly decided to support Python 3 beginning with version 3.9. -Reasons for this include: - -- Encouraging use of newest versions of Python 3 -- Taking the lead of `prominent`_ open-source `projects`_ -- `Unicode literal support`_ which allows for a cleaner codebase that - works in both Python 2 and Python 3 - -.. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django -.. _projects: http://flask.pocoo.org/docs/0.10/python3/ -.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/ - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-cloud-spanner-dbapi-driver/CONTRIBUTING.rst b/packages/google-cloud-spanner-dbapi-driver/CONTRIBUTING.rst new file mode 100644 index 000000000000..4d6e87dd6421 --- /dev/null +++ b/packages/google-cloud-spanner-dbapi-driver/CONTRIBUTING.rst @@ -0,0 +1,11 @@ +############ +Contributing +############ + +This package is part of the ``google-cloud-python`` monorepo. + +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. + +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst + +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-cloud-spanner/CONTRIBUTING.rst b/packages/google-cloud-spanner/CONTRIBUTING.rst new file mode 100644 index 000000000000..4d6e87dd6421 --- /dev/null +++ b/packages/google-cloud-spanner/CONTRIBUTING.rst @@ -0,0 +1,11 @@ +############ +Contributing +############ + +This package is part of the ``google-cloud-python`` monorepo. + +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. + +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst + +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-cloud-storage/CONTRIBUTING.rst b/packages/google-cloud-storage/CONTRIBUTING.rst index 87747c9460c5..4d6e87dd6421 100644 --- a/packages/google-cloud-storage/CONTRIBUTING.rst +++ b/packages/google-cloud-storage/CONTRIBUTING.rst @@ -1,259 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 - ``python-storage`` `repo`_ on GitHub. - -- Fork and clone the ``python-storage`` repository to your GitHub account by - clicking the "Fork" button. - -- Clone your fork of ``python-storage`` from your GitHub account to your local - computer, substituting your account username and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-storage - -Using ``nox`` -============= - -We use `nox `__ to instrument our tests. - -- To test your changes, run unit tests with ``nox``:: - - $ nox -s unit-3.9 - $ ... - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 -************ - -- PEP8 compliance, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``python-storage``. The the suggested remote name ``upstream`` - should point to the official ``googleapis`` checkout and the - the branch should be the main branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - $ nox -s system-3.14 - - .. note:: - - System tests are configured to run under Python 3.14 in ``noxfile.py``. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project and - so you'll need to provide some environment variables to facilitate - authentication to your project: - - - ``GOOGLE_APPLICATION_CREDENTIALS``: The path to a JSON key file; - Such a file can be downloaded directly from the developer's console by clicking - "Generate new JSON key". See private key - `docs `__ - for more details. - -- Once you have downloaded your json keys, set the environment variable - ``GOOGLE_APPLICATION_CREDENTIALS`` to the absolute path of the json file:: - - $ export GOOGLE_APPLICATION_CREDENTIALS="/Users//path/to/app_credentials.json" - - -************* -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 - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/packages/google-cloud-storage/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/google-cloud-storage - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.7`_ -- `Python 3.8`_ -- `Python 3.9`_ -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.7: https://docs.python.org/3.7/ -.. _Python 3.8: https://docs.python.org/3.8/ -.. _Python 3.9: https://docs.python.org/3.9/ -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - -Supported versions can be found in our ``noxfile.py`` `config`_. - -We also explicitly decided to support Python 3 beginning with version 3.9. Reasons for this include: - -- Encouraging use of newest versions of Python 3 -- Taking the lead of `prominent`_ open-source `projects`_ -- `Unicode literal support`_ which allows for a cleaner codebase that - works in both Python 2 and Python 3 - -.. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django -.. _projects: http://flask.pocoo.org/docs/0.10/python3/ -.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/ - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-cloud-testutils/CONTRIBUTING.rst b/packages/google-cloud-testutils/CONTRIBUTING.rst new file mode 100644 index 000000000000..4d6e87dd6421 --- /dev/null +++ b/packages/google-cloud-testutils/CONTRIBUTING.rst @@ -0,0 +1,11 @@ +############ +Contributing +############ + +This package is part of the ``google-cloud-python`` monorepo. + +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. + +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst + +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-crc32c/CONTRIBUTING.md b/packages/google-crc32c/CONTRIBUTING.md deleted file mode 100644 index ebbb59e5310f..000000000000 --- a/packages/google-crc32c/CONTRIBUTING.md +++ /dev/null @@ -1,28 +0,0 @@ -# How to Contribute - -We'd love to accept your patches and contributions to this project. There are -just a few small guidelines you need to follow. - -## Contributor License Agreement - -Contributions to this project must be accompanied by a Contributor License -Agreement. You (or your employer) retain the copyright to your contribution; -this simply gives us permission to use and redistribute your contributions as -part of the project. Head over to to see -your current agreements on file or to sign a new one. - -You generally only need to submit a CLA once, so if you've already submitted one -(even if it was for a different project), you probably don't need to do it -again. - -## Code reviews - -All submissions, including submissions by project members, require review. We -use GitHub pull requests for this purpose. Consult -[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more -information on using pull requests. - -## Community Guidelines - -This project follows -[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/). \ No newline at end of file diff --git a/packages/google-crc32c/CONTRIBUTING.rst b/packages/google-crc32c/CONTRIBUTING.rst new file mode 100644 index 000000000000..4d6e87dd6421 --- /dev/null +++ b/packages/google-crc32c/CONTRIBUTING.rst @@ -0,0 +1,11 @@ +############ +Contributing +############ + +This package is part of the ``google-cloud-python`` monorepo. + +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. + +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst + +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/google-resumable-media/CONTRIBUTING.md b/packages/google-resumable-media/CONTRIBUTING.md deleted file mode 100644 index 6272489dae31..000000000000 --- a/packages/google-resumable-media/CONTRIBUTING.md +++ /dev/null @@ -1,28 +0,0 @@ -# How to Contribute - -We'd love to accept your patches and contributions to this project. There are -just a few small guidelines you need to follow. - -## Contributor License Agreement - -Contributions to this project must be accompanied by a Contributor License -Agreement. You (or your employer) retain the copyright to your contribution; -this simply gives us permission to use and redistribute your contributions as -part of the project. Head over to to see -your current agreements on file or to sign a new one. - -You generally only need to submit a CLA once, so if you've already submitted one -(even if it was for a different project), you probably don't need to do it -again. - -## Code Reviews - -All submissions, including submissions by project members, require review. We -use GitHub pull requests for this purpose. Consult -[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more -information on using pull requests. - -## Community Guidelines - -This project follows [Google's Open Source Community -Guidelines](https://opensource.google/conduct/). diff --git a/packages/google-resumable-media/CONTRIBUTING.rst b/packages/google-resumable-media/CONTRIBUTING.rst new file mode 100644 index 000000000000..4d6e87dd6421 --- /dev/null +++ b/packages/google-resumable-media/CONTRIBUTING.rst @@ -0,0 +1,11 @@ +############ +Contributing +############ + +This package is part of the ``google-cloud-python`` monorepo. + +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. + +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst + +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/googleapis-common-protos/CONTRIBUTING.md b/packages/googleapis-common-protos/CONTRIBUTING.md deleted file mode 100644 index b16a4668cb64..000000000000 --- a/packages/googleapis-common-protos/CONTRIBUTING.md +++ /dev/null @@ -1,29 +0,0 @@ -# How to Contribute - -We'd love to accept your patches and contributions to this project. There are -just a few small guidelines you need to follow. - -## Contributor License Agreement - -Contributions to this project must be accompanied by a Contributor License -Agreement (CLA). You (or your employer) retain the copyright to your -contribution; this simply gives us permission to use and redistribute your -contributions as part of the project. Head over to - to see your current agreements on file or -to sign a new one. - -You generally only need to submit a CLA once, so if you've already submitted one -(even if it was for a different project), you probably don't need to do it -again. - -## Code reviews - -All submissions, including submissions by project members, require review. We -use GitHub pull requests for this purpose. Consult -[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more -information on using pull requests. - -## Community Guidelines - -This project follows -[Google's Open Source Community Guidelines](https://opensource.google/conduct/). \ No newline at end of file diff --git a/packages/googleapis-common-protos/CONTRIBUTING.rst b/packages/googleapis-common-protos/CONTRIBUTING.rst new file mode 100644 index 000000000000..4d6e87dd6421 --- /dev/null +++ b/packages/googleapis-common-protos/CONTRIBUTING.rst @@ -0,0 +1,11 @@ +############ +Contributing +############ + +This package is part of the ``google-cloud-python`` monorepo. + +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. + +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst + +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/pandas-gbq/CONTRIBUTING.rst b/packages/pandas-gbq/CONTRIBUTING.rst index 92c64fb609fb..4d6e87dd6421 100644 --- a/packages/pandas-gbq/CONTRIBUTING.rst +++ b/packages/pandas-gbq/CONTRIBUTING.rst @@ -1,281 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 - ``python-bigquery-pandas`` `repo`_ on GitHub. - -- Fork and clone the ``python-bigquery-pandas`` repository to your GitHub account by - clicking the "Fork" button. - -- Clone your fork of ``python-bigquery-pandas`` from your GitHub account to your local - computer, substituting your account username and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python/tree/main/packages/pandas-gbq - -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:: - - $ nox -s unit-3.14 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``python-bigquery-pandas``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.14 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.14. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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/` catalogue. 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. If you decide to create a new folder, you can -base it on the `samples/snippets` folder (providing `noxfile.py` and -the requirements files). - -The tests will run against a real Google Cloud Project, so you should -configure them just like the System Tests. - -- To run sample tests, you can execute:: - - # Run all tests in a folder - $ cd samples/snippets - $ nox -s py-3.10 - - # Run a single sample test - $ cd samples/snippets - $ nox -s py-3.10 -- -k - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/packages/pandas-gbq/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/pandas-gbq - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/packages/pandas-gbq/noxfile.py - - -We also explicitly decided to support Python 3 beginning with version 3.10. -Reasons for this include: - -- Encouraging use of newest versions of Python 3 -- Taking the lead of `prominent`_ open-source `projects`_ -- `Unicode literal support`_ which allows for a cleaner codebase that - works in both Python 2 and Python 3 - -.. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django -.. _projects: http://flask.pocoo.org/docs/0.10/python3/ -.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/ - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/proto-plus/CONTRIBUTING.rst b/packages/proto-plus/CONTRIBUTING.rst new file mode 100644 index 000000000000..4d6e87dd6421 --- /dev/null +++ b/packages/proto-plus/CONTRIBUTING.rst @@ -0,0 +1,11 @@ +############ +Contributing +############ + +This package is part of the ``google-cloud-python`` monorepo. + +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. + +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst + +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/sqlalchemy-bigquery/CONTRIBUTING.rst b/packages/sqlalchemy-bigquery/CONTRIBUTING.rst index 7db9f22985ff..4d6e87dd6421 100644 --- a/packages/sqlalchemy-bigquery/CONTRIBUTING.rst +++ b/packages/sqlalchemy-bigquery/CONTRIBUTING.rst @@ -1,270 +1,11 @@ -.. Generated by synthtool. DO NOT EDIT! ############ 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. (Please Read: `Faster Pull Request Reviews`_) +This package is part of the ``google-cloud-python`` monorepo. -.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. -.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries. +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst -*************** -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 the following CPython versions: - 3.10, 3.11, 3.12, 3.13 and 3.14 on both UNIX and Windows. - -- The feature must not add unnecessary dependencies (where - "unnecessary" is of course 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 - ``python-bigquery-sqlalchemy`` `repo`_ on GitHub. - -- Fork and clone the ``python-bigquery-sqlalchemy`` repository to your GitHub account by - clicking the "Fork" button. - -- Clone your fork of ``python-bigquery-sqlalchemy`` from your GitHub account to your local - computer, substituting your account username and specifying the destination - as ``hack-on-google-cloud-python``. E.g.:: - - $ 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 - $ 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. - -.. _repo: https://github.com/googleapis/google-cloud-python/tree/main/packages/sqlalchemy-bigquery - -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:: - - $ nox -s unit-3.14 -- -k - - - .. note:: - - The unit tests and system tests are described in the - ``noxfile.py`` files in each directory. - -.. nox: https://pypi.org/project/nox/ - -***************************************** -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 the automatic code formatter ``black``. You can run it using - the nox session ``blacken``. This will eliminate many lint errors. Run via:: - - $ nox -s blacken - -- PEP8 compliance is required, with exceptions defined in the linter configuration. - If you have ``nox`` installed, you can test that you have not introduced - any non-compliant code via:: - - $ nox -s lint - -- In order to make ``nox -s lint`` run faster, you can set some environment - variables:: - - export GOOGLE_CLOUD_TESTING_REMOTE="upstream" - export GOOGLE_CLOUD_TESTING_BRANCH="main" - - By doing this, you are specifying the location of the most up-to-date - version of ``python-bigquery-sqlalchemy``. The - remote name ``upstream`` should point to the official ``googleapis`` - checkout and the branch should be the default branch on that remote (``main``). - -- 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: - -.. code-block:: bash - - $ 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 -******************** - -- To run system tests, you can execute:: - - # Run all system tests - $ nox -s system - - # Run a single system test - $ nox -s system-3.14 -- -k - - - .. note:: - - System tests are only configured to run under Python 3.12 and 3.14. - For expediency, we do not run them in older versions of Python 3. - - This alone will not run the tests. You'll need to change some local - auth settings and change some configuration in your project to - run all the tests. - -- System tests will be run against an actual project. You should use local credentials from gcloud when possible. See `Best practices for application authentication `__. Some tests require a service account. For those tests see `Authenticating as a service account `__. - -************* -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/` catalogue. 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. If you decide to create a new folder, you can -base it on the `samples/snippets` folder (providing `noxfile.py` and -the requirements files). - -The tests will run against a real Google Cloud Project, so you should -configure them just like the System Tests. - -- To run sample tests, you can execute:: - - # Run all tests in a folder - $ cd samples/snippets - $ nox -s py-3.10 - - # Run a single sample test - $ cd samples/snippets - $ nox -s py-3.10 -- -k - -******************************************** -Note About ``README`` as it pertains to PyPI -******************************************** - -The `description on PyPI`_ for the project comes directly from the -``README``. Due to the reStructuredText (``rst``) parser used by -PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst`` -instead of -``https://github.com/googleapis/google-cloud-python/blob/main/packages/sqlalchemy-bigquery/CONTRIBUTING.rst``) -may cause problems creating links or rendering the description. - -.. _description on PyPI: https://pypi.org/project/sqlalchemy-bigquery - - -************************* -Supported Python Versions -************************* - -We support: - -- `Python 3.10`_ -- `Python 3.11`_ -- `Python 3.12`_ -- `Python 3.13`_ -- `Python 3.14`_ - -.. _Python 3.10: https://docs.python.org/3.10/ -.. _Python 3.11: https://docs.python.org/3.11/ -.. _Python 3.12: https://docs.python.org/3.12/ -.. _Python 3.13: https://docs.python.org/3.13/ -.. _Python 3.14: https://docs.python.org/3.14/ - - -Supported versions can be found in our ``noxfile.py`` `config`_. - -.. _config: https://github.com/googleapis/google-cloud-python/blob/main/packages/sqlalchemy-bigquery/noxfile.py - - - -********** -Versioning -********** - -This library follows `Semantic Versioning`_. - -.. _Semantic Versioning: http://semver.org/ - -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. +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. diff --git a/packages/sqlalchemy-spanner/CONTRIBUTING.md b/packages/sqlalchemy-spanner/CONTRIBUTING.md deleted file mode 100644 index 6294c4529e49..000000000000 --- a/packages/sqlalchemy-spanner/CONTRIBUTING.md +++ /dev/null @@ -1,54 +0,0 @@ -# How to Contribute - -We'd love to accept your patches and contributions to this project. There are -just a few small guidelines you need to follow. - -## Contributor License Agreement - -Contributions to this project must be accompanied by a Contributor License -Agreement. You (or your employer) retain the copyright to your contribution; -this simply gives us permission to use and redistribute your contributions as -part of the project. Head over to to see -your current agreements on file or to sign a new one. - -You generally only need to submit a CLA once, so if you've already submitted one -(even if it was for a different project), you probably don't need to do it -again. - -## Code Reviews - -All submissions, including submissions by project members, require review. We -use GitHub pull requests for this purpose. Consult -[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more -information on using pull requests. - -## Community Guidelines - -This project follows [Google's Open Source Community -Guidelines](https://opensource.google/conduct/). - -## Running tests - -SQLAlchemy Spanner dialect includes a test suite, which can be executed both on a live service and Spanner emulator. - -**Using pytest** -To execute the test suite with standard `pytest` package you only need to checkout to the package folder and run: -``` -pytest -v -``` - -**Using nox** -The package includes a configuration file for `nox` package, which allows to execute the dialect test suite in an isolated virtual environment. To execute all the `nox` sessions checkout to the dialect folder and then run command: -``` -nox -``` -To execute only the dialect compliance test suite execute command: -``` -nox -s compliance_test -``` - -**Live service** -To run the test suite on a live service use [setup.cfg](https://github.com/cloudspannerecosystem/python-spanner-sqlalchemy/blob/main/setup.cfg) `db.default` attribute to set URI of the project, instance and database, where the tests should be executed. - -**Emulator** -As the dialect is built on top of the Spanner DB API, it also supports running on Spanner emulator. To make it happen you need to set an environment variable, pointing to the emulator service, for example `SPANNER_EMULATOR_HOST=localhost:9010` \ No newline at end of file diff --git a/packages/sqlalchemy-spanner/CONTRIBUTING.rst b/packages/sqlalchemy-spanner/CONTRIBUTING.rst new file mode 100644 index 000000000000..16826f25daa5 --- /dev/null +++ b/packages/sqlalchemy-spanner/CONTRIBUTING.rst @@ -0,0 +1,37 @@ +############ +Contributing +############ + +This package is part of the ``google-cloud-python`` monorepo. + +Please refer to the centralized `Contributing Guide`_ at the repository root for general guidelines on how to contribute, set up your development environment, and submit pull requests. + +.. _Contributing Guide: https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.rst + +Package-specific test sessions are defined in this directory's ``noxfile.py``. Dependencies and supported Python versions are defined in ``setup.py`` or ``pyproject.toml``. + +******************** +Running Tests +******************** + +SQLAlchemy Spanner dialect includes a test suite, which can be executed both on a live service and Spanner emulator. + +**Using pytest** +To execute the test suite with standard ``pytest`` package you only need to checkout to the package folder and run:: + + pytest -v + +**Using nox** +The package includes a configuration file for ``nox`` package, which allows to execute the dialect test suite in an isolated virtual environment. To execute all the ``nox`` sessions checkout to the dialect folder and then run command:: + + nox + +To execute only the dialect compliance test suite execute command:: + + nox -s compliance_test + +**Live service** +To run the test suite on a live service use ``setup.cfg`` ``db.default`` attribute to set URI of the project, instance and database, where the tests should be executed. + +**Emulator** +As the dialect is built on top of the Spanner DB API, it also supports running on Spanner emulator. To make it happen you need to set an environment variable, pointing to the emulator service, for example ``SPANNER_EMULATOR_HOST=localhost:9010``