diff options
author | Anthonios Partheniou <partheniou@google.com> | 2021-12-28 14:24:12 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-12-28 19:24:12 +0000 |
commit | d94a4cc12a4ee08d16f0576c4dc9a40933219a05 (patch) | |
tree | 3563d9290ec05eb0454586d927c0a44bdde3428d | |
parent | 5a6231d31156644fdc0fd5a6ef8a0cef25d1dd9b (diff) | |
download | google-api-python-client-d94a4cc12a4ee08d16f0576c4dc9a40933219a05.tar.gz |
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 🦕
-rw-r--r-- | CONTRIBUTING.rst | 312 | ||||
-rw-r--r-- | owlbot.py | 3 |
2 files changed, 269 insertions, 46 deletions
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 8af7af6b4..9c1114009 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. -.. 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 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 -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. @@ -35,6 +35,9 @@ s.move(templated_files / '.github', excludes=['CODEOWNERS']) # Move scripts folder needed for samples CI s.move(templated_files / 'scripts') +# Copy CONTRIBUTING.rst +s.move(templated_files / 'CONTRIBUTING.rst') + # ---------------------------------------------------------------------------- # Samples templates # ---------------------------------------------------------------------------- |