docs: centralize CONTRIBUTING.rst pointers

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 <https://nox.readthedocs.io/en/latest/>`__ to instrument our tests.
+
+- To test your changes, run unit tests with ``nox``::
+
+    $ nox -s unit
+
+- To run a single unit test (replace `<python_version>` with a supported version, e.g., ``3.10``)::
+
+    $ nox -s unit-<python_version> -- -k <name of test>
+
+  .. note::
+
+    The unit tests and system tests are described in the ``noxfile.py`` files in each package directory.
+
+.. _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 <https://pre-commit.com/>`__ 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 <https://cloud.google.com/docs/authentication/best-practices-applications#local_development_and_testing_with_the>`__. Some tests require a service account. For those tests see `Authenticating as a service account <https://cloud.google.com/docs/authentication/production>`__.
+
+.. 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 <https://developers.google.com/open-source/cla/individual>`__.
-- **If you work for a company that wants to allow you to contribute your work**,
-  then you'll need to sign a
-  `corporate CLA <https://developers.google.com/open-source/cla/corporate>`__.
+- **If you are an individual writing original source code** and **you own the intellectual property**, then you'll need to sign an `individual CLA <https://developers.google.com/open-source/cla/individual>`__.
+- **If you work for a company that wants to allow you to contribute your work**, then you'll need to sign a `corporate CLA <https://developers.google.com/open-source/cla/corporate>`__.
 
-You can sign these electronically (just scroll to the bottom). After that,
-we'll be able to accept your pull requests.
+You can sign these electronically (just scroll to the bottom). After that, we'll be able to accept your pull requests.