chore: update CONTRIBUTING doc (#1639)
This PR updates [CONTRIBUTING.rst](https://github.com/googleapis/google-api-python-client/blob/main/CONTRIBUTING.rst) to use the templated version from synthtool templates [here](https://github.com/googleapis/synthtool/blob/master/synthtool/gcp/templates/python_library/CONTRIBUTING.rst).
Fixes #1634 🦕
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 8af7af6..9c11140 100644
--- a/CONTRIBUTING.rst
+++ b/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.
+
+- 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.::
+
+ $ cd ${HOME}
+ $ git clone git@github.com: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 git@github.com:googleapis/google-api-python-client.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-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::
+ .. note::
- 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.
+ The unit tests and system tests are described in the
+ ``noxfile.py`` files in each directory.
-For more information about Nox, including command-line usage, consult
-`nox documentation <https://nox.thea.codes/>`__.
+.. 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.
diff --git a/owlbot.py b/owlbot.py
index 0d995c1..4a03f4b 100644
--- a/owlbot.py
+++ b/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
# ----------------------------------------------------------------------------