chore: update CONTRIBUTING doc

CONTRIBUTING.rst

@@ -1,61 +1,281 @@
-How to Contribute
-=================
+.. Generated by synthtool. DO NOT EDIT!
+############
+Contributing
+############
 
-We'd love to accept your patches and contributions to this project.
-There are a few guidelines described in our
-`Contribution Guide <http://google.github.io/google-api-python-client/contributing.html>`__
-that you need to follow.
+#. **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`_)
 
-To summarize here: when contributing, please:
+.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews
 
-* Sign Contributor License Agreement
-* Before making changes, file an issue
-* Fork this repository and use github pull requests for all submissions
-* Follow
-  `Contributor Code of Conduct
-  <https://github.com/googleapis/google-api-python-client/blob/main/CODE_OF_CONDUCT.md>`__
-  and `Community Guidelines <https://opensource.google/conduct/>`__
-* Follow `Google Python Style Guide <https://google.github.io/styleguide/pyguide.html>`__
-  and `this commit authoring style <http://chris.beams.io/posts/git-commit/#seven-rules>`__
-* Don't forget to write tests and update documentation!
+.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries.
 
-Setup Notes
------------
+***************
+Adding Features
+***************
 
-Please follow these steps after forking and cloning the repository
-to make sure you can modify code and run tests with confidence::
+In order to add a feature:
 
-    # From the root dir of the cloned repository:
-    # Create Virtual Environment called env (you may choose your own name)
-    python3 -m venv env
+- The feature must be documented in both the API and narrative
+  documentation.
 
-    # Activate virtual environment
-    source env/bin/activate
+- The feature must work fully on the following CPython versions:
+  3.6, 3.7, 3.8, 3.9 and 3.10 on both UNIX and Windows.
 
-    # Install this library as editable install
-    # (see https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-e)
-    python3 -m pip install -e .
+- The feature must not add unnecessary dependencies (where
+  "unnecessary" is of course subjective, but new dependencies should
+  be discussed).
 
-    # Install nox
-    python3 -m pip install nox
+****************************
+Using a Development Checkout
+****************************
 
-We use `nox <https://nox.thea.codes/>`__ to instrument our tests.
-To test your changes, run unit tests with ``nox``::
+You'll have to create a development environment using a Git checkout:
 
-    # Run tests for all supported versions of Python and oauth2client:
-    nox
-    # Run tests for Python 3.7:
-    nox -s unit-3.7
-    # Run lint
-    nox -s lint
+- While logged into your GitHub account, navigate to the
+  ``google-api-python-client`` `repo`_ on GitHub.
 
+- Fork and clone the ``google-api-python-client`` repository to your GitHub account by
+  clicking the "Fork" button.
 
-.. note::
+- Clone your fork of ``google-api-python-client`` from your GitHub account to your local
+  computer, substituting your account username and specifying the destination
+  as ``hack-on-google-api-python-client``.  E.g.::
 
-  The unit tests and system tests are described in the
-  ``noxfile.py`` file in this directory. Nox will automatically
-  handle constriction of new virtual environments and installation
-  of the required test dependencies.
+   $ cd ${HOME}
+   $ git clone [email protected]:USERNAME/google-api-python-client.git hack-on-google-api-python-client
+   $ cd hack-on-google-api-python-client
+   # Configure remotes such that you can pull changes from the googleapis/google-api-python-client
+   # repository into your local repository.
+   $ git remote add upstream [email protected]:googleapis/google-api-python-client.git
+   # fetch and merge changes from upstream into main
+   $ git fetch upstream
+   $ git merge upstream/main
 
-For more information about Nox, including command-line usage, consult
-`nox documentation <https://nox.thea.codes/>`__.
+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-api-python-client
+
+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::
+
+    $ nox -s unit-3.10 -- -k <name of test>
+
+
+  .. 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-api-python-client``. 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 <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
+
+   # Run a single system test
+   $ nox -s system-3.8 -- -k <name of test>
+
+
+  .. 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 <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>`__.
+
+*************
+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 <name of test>
+
+********************************************
+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-api-python-client/blob/main/CONTRIBUTING.rst``)
+may cause problems creating links or rendering the description.
+
+.. _description on PyPI: https://pypi.org/project/google-api-python-client
+
+
+*************************
+Supported Python Versions
+*************************
+
+We support:
+
+-  `Python 3.6`_
+-  `Python 3.7`_
+-  `Python 3.8`_
+-  `Python 3.9`_
+-  `Python 3.10`_
+
+.. _Python 3.6: https://docs.python.org/3.6/
+.. _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/
+
+
+Supported versions can be found in our ``noxfile.py`` `config`_.
+
+.. _config: https://github.com/googleapis/google-api-python-client/blob/main/noxfile.py
+
+
+We also explicitly decided to support Python 3 beginning with version 3.6.
+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 <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.

owlbot.py

@@ -35,6 +35,9 @@
 # Move scripts folder needed for samples CI
 s.move(templated_files / 'scripts')
 
+# Copy CONTRIBUTING.rst
+s.move(templated_files / 'CONTRIBUTING.rst')
+
 # ----------------------------------------------------------------------------
 # Samples templates
 # ----------------------------------------------------------------------------