Skip to content

Commit d94a4cc

Browse files
partheaparthea
authored
chore: update CONTRIBUTING doc (googleapis#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 googleapis#1634 🦕
1 parent 5a6231d commit d94a4cc

File tree

2 files changed

+269
-46
lines changed

2 files changed

+269
-46
lines changed

‎CONTRIBUTING.rst

+266-46
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,281 @@
1-
How to Contribute
2-
=================
1+
.. Generated by synthtool. DO NOT EDIT!
2+
############
3+
Contributing
4+
############
35

4-
We'd love to accept your patches and contributions to this project.
5-
There are a few guidelines described in our
6-
`Contribution Guide <http://google.github.io/google-api-python-client/contributing.html>`__
7-
that you need to follow.
6+
#. **Please sign one of the contributor license agreements below.**
7+
#. Fork the repo, develop and test your code changes, add docs.
8+
#. Make sure that your commit messages clearly describe the changes.
9+
#. Send a pull request. (Please Read: `Faster Pull Request Reviews`_)
810

9-
To summarize here: when contributing, please:
11+
.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews
1012

11-
* Sign Contributor License Agreement
12-
* Before making changes, file an issue
13-
* Fork this repository and use github pull requests for all submissions
14-
* Follow
15-
`Contributor Code of Conduct
16-
<https://github.com/googleapis/google-api-python-client/blob/main/CODE_OF_CONDUCT.md>`__
17-
and `Community Guidelines <https://opensource.google/conduct/>`__
18-
* Follow `Google Python Style Guide <https://google.github.io/styleguide/pyguide.html>`__
19-
and `this commit authoring style <http://chris.beams.io/posts/git-commit/#seven-rules>`__
20-
* Don't forget to write tests and update documentation!
13+
.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries.
2114

22-
Setup Notes
23-
-----------
15+
***************
16+
Adding Features
17+
***************
2418

25-
Please follow these steps after forking and cloning the repository
26-
to make sure you can modify code and run tests with confidence::
19+
In order to add a feature:
2720

28-
# From the root dir of the cloned repository:
29-
# Create Virtual Environment called env (you may choose your own name)
30-
python3 -m venv env
21+
- The feature must be documented in both the API and narrative
22+
documentation.
3123

32-
# Activate virtual environment
33-
source env/bin/activate
24+
- The feature must work fully on the following CPython versions:
25+
3.6, 3.7, 3.8, 3.9 and 3.10 on both UNIX and Windows.
3426

35-
# Install this library as editable install
36-
# (see https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-e)
37-
python3 -m pip install -e .
27+
- The feature must not add unnecessary dependencies (where
28+
"unnecessary" is of course subjective, but new dependencies should
29+
be discussed).
3830

39-
# Install nox
40-
python3 -m pip install nox
31+
****************************
32+
Using a Development Checkout
33+
****************************
4134

42-
We use `nox <https://nox.thea.codes/>`__ to instrument our tests.
43-
To test your changes, run unit tests with ``nox``::
35+
You'll have to create a development environment using a Git checkout:
4436

45-
# Run tests for all supported versions of Python and oauth2client:
46-
nox
47-
# Run tests for Python 3.7:
48-
nox -s unit-3.7
49-
# Run lint
50-
nox -s lint
37+
- While logged into your GitHub account, navigate to the
38+
``google-api-python-client`` `repo`_ on GitHub.
5139

40+
- Fork and clone the ``google-api-python-client`` repository to your GitHub account by
41+
clicking the "Fork" button.
5242

53-
.. note::
43+
- Clone your fork of ``google-api-python-client`` from your GitHub account to your local
44+
computer, substituting your account username and specifying the destination
45+
as ``hack-on-google-api-python-client``. E.g.::
5446

55-
The unit tests and system tests are described in the
56-
``noxfile.py`` file in this directory. Nox will automatically
57-
handle constriction of new virtual environments and installation
58-
of the required test dependencies.
47+
$ cd ${HOME}
48+
$ git clone [email protected]:USERNAME/google-api-python-client.git hack-on-google-api-python-client
49+
$ cd hack-on-google-api-python-client
50+
# Configure remotes such that you can pull changes from the googleapis/google-api-python-client
51+
# repository into your local repository.
52+
$ git remote add upstream [email protected]:googleapis/google-api-python-client.git
53+
# fetch and merge changes from upstream into main
54+
$ git fetch upstream
55+
$ git merge upstream/main
5956

60-
For more information about Nox, including command-line usage, consult
61-
`nox documentation <https://nox.thea.codes/>`__.
57+
Now your local repo is set up such that you will push changes to your GitHub
58+
repo, from which you can submit a pull request.
59+
60+
To work on the codebase and run the tests, we recommend using ``nox``,
61+
but you can also use a ``virtualenv`` of your own creation.
62+
63+
.. _repo: https://github.com/googleapis/google-api-python-client
64+
65+
Using ``nox``
66+
=============
67+
68+
We use `nox <https://nox.readthedocs.io/en/latest/>`__ to instrument our tests.
69+
70+
- To test your changes, run unit tests with ``nox``::
71+
$ nox -s unit
72+
73+
- To run a single unit test::
74+
75+
$ nox -s unit-3.10 -- -k <name of test>
76+
77+
78+
.. note::
79+
80+
The unit tests and system tests are described in the
81+
``noxfile.py`` files in each directory.
82+
83+
.. nox: https://pypi.org/project/nox/
84+
85+
*****************************************
86+
I'm getting weird errors... Can you help?
87+
*****************************************
88+
89+
If the error mentions ``Python.h`` not being found,
90+
install ``python-dev`` and try again.
91+
On Debian/Ubuntu::
92+
93+
$ sudo apt-get install python-dev
94+
95+
************
96+
Coding Style
97+
************
98+
- We use the automatic code formatter ``black``. You can run it using
99+
the nox session ``blacken``. This will eliminate many lint errors. Run via::
100+
101+
$ nox -s blacken
102+
103+
- PEP8 compliance is required, with exceptions defined in the linter configuration.
104+
If you have ``nox`` installed, you can test that you have not introduced
105+
any non-compliant code via::
106+
107+
$ nox -s lint
108+
109+
- In order to make ``nox -s lint`` run faster, you can set some environment
110+
variables::
111+
112+
export GOOGLE_CLOUD_TESTING_REMOTE="upstream"
113+
export GOOGLE_CLOUD_TESTING_BRANCH="main"
114+
115+
By doing this, you are specifying the location of the most up-to-date
116+
version of ``google-api-python-client``. The
117+
remote name ``upstream`` should point to the official ``googleapis``
118+
checkout and the branch should be the default branch on that remote (``main``).
119+
120+
- This repository contains configuration for the
121+
`pre-commit <https://pre-commit.com/>`__ tool, which automates checking
122+
our linters during a commit. If you have it installed on your ``$PATH``,
123+
you can enable enforcing those checks via:
124+
125+
.. code-block:: bash
126+
127+
$ pre-commit install
128+
pre-commit installed at .git/hooks/pre-commit
129+
130+
Exceptions to PEP8:
131+
132+
- Many unit tests use a helper method, ``_call_fut`` ("FUT" is short for
133+
"Function-Under-Test"), which is PEP8-incompliant, but more readable.
134+
Some also use a local variable, ``MUT`` (short for "Module-Under-Test").
135+
136+
********************
137+
Running System Tests
138+
********************
139+
140+
- To run system tests, you can execute::
141+
142+
# Run all system tests
143+
$ nox -s system
144+
145+
# Run a single system test
146+
$ nox -s system-3.8 -- -k <name of test>
147+
148+
149+
.. note::
150+
151+
System tests are only configured to run under Python 3.8.
152+
For expediency, we do not run them in older versions of Python 3.
153+
154+
This alone will not run the tests. You'll need to change some local
155+
auth settings and change some configuration in your project to
156+
run all the tests.
157+
158+
- 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>`__.
159+
160+
*************
161+
Test Coverage
162+
*************
163+
164+
- The codebase *must* have 100% test statement coverage after each commit.
165+
You can test coverage via ``nox -s cover``.
166+
167+
******************************************************
168+
Documentation Coverage and Building HTML Documentation
169+
******************************************************
170+
171+
If you fix a bug, and the bug requires an API or behavior modification, all
172+
documentation in this package which references that API or behavior must be
173+
changed to reflect the bug fix, ideally in the same commit that fixes the bug
174+
or adds the feature.
175+
176+
Build the docs via:
177+
178+
$ nox -s docs
179+
180+
*************************
181+
Samples and code snippets
182+
*************************
183+
184+
Code samples and snippets live in the `samples/` catalogue. Feel free to
185+
provide more examples, but make sure to write tests for those examples.
186+
Each folder containing example code requires its own `noxfile.py` script
187+
which automates testing. If you decide to create a new folder, you can
188+
base it on the `samples/snippets` folder (providing `noxfile.py` and
189+
the requirements files).
190+
191+
The tests will run against a real Google Cloud Project, so you should
192+
configure them just like the System Tests.
193+
194+
- To run sample tests, you can execute::
195+
196+
# Run all tests in a folder
197+
$ cd samples/snippets
198+
$ nox -s py-3.8
199+
200+
# Run a single sample test
201+
$ cd samples/snippets
202+
$ nox -s py-3.8 -- -k <name of test>
203+
204+
********************************************
205+
Note About ``README`` as it pertains to PyPI
206+
********************************************
207+
208+
The `description on PyPI`_ for the project comes directly from the
209+
``README``. Due to the reStructuredText (``rst``) parser used by
210+
PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst``
211+
instead of
212+
``https://github.com/googleapis/google-api-python-client/blob/main/CONTRIBUTING.rst``)
213+
may cause problems creating links or rendering the description.
214+
215+
.. _description on PyPI: https://pypi.org/project/google-api-python-client
216+
217+
218+
*************************
219+
Supported Python Versions
220+
*************************
221+
222+
We support:
223+
224+
- `Python 3.6`_
225+
- `Python 3.7`_
226+
- `Python 3.8`_
227+
- `Python 3.9`_
228+
- `Python 3.10`_
229+
230+
.. _Python 3.6: https://docs.python.org/3.6/
231+
.. _Python 3.7: https://docs.python.org/3.7/
232+
.. _Python 3.8: https://docs.python.org/3.8/
233+
.. _Python 3.9: https://docs.python.org/3.9/
234+
.. _Python 3.10: https://docs.python.org/3.10/
235+
236+
237+
Supported versions can be found in our ``noxfile.py`` `config`_.
238+
239+
.. _config: https://github.com/googleapis/google-api-python-client/blob/main/noxfile.py
240+
241+
242+
We also explicitly decided to support Python 3 beginning with version 3.6.
243+
Reasons for this include:
244+
245+
- Encouraging use of newest versions of Python 3
246+
- Taking the lead of `prominent`_ open-source `projects`_
247+
- `Unicode literal support`_ which allows for a cleaner codebase that
248+
works in both Python 2 and Python 3
249+
250+
.. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django
251+
.. _projects: http://flask.pocoo.org/docs/0.10/python3/
252+
.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/
253+
254+
**********
255+
Versioning
256+
**********
257+
258+
This library follows `Semantic Versioning`_.
259+
260+
.. _Semantic Versioning: http://semver.org/
261+
262+
Some packages are currently in major version zero (``0.y.z``), which means that
263+
anything may change at any time and the public API should not be considered
264+
stable.
265+
266+
******************************
267+
Contributor License Agreements
268+
******************************
269+
270+
Before we can accept your pull requests you'll need to sign a Contributor
271+
License Agreement (CLA):
272+
273+
- **If you are an individual writing original source code** and **you own the
274+
intellectual property**, then you'll need to sign an
275+
`individual CLA <https://developers.google.com/open-source/cla/individual>`__.
276+
- **If you work for a company that wants to allow you to contribute your work**,
277+
then you'll need to sign a
278+
`corporate CLA <https://developers.google.com/open-source/cla/corporate>`__.
279+
280+
You can sign these electronically (just scroll to the bottom). After that,
281+
we'll be able to accept your pull requests.

‎owlbot.py

+3
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,9 @@
3535
# Move scripts folder needed for samples CI
3636
s.move(templated_files / 'scripts')
3737

38+
# Copy CONTRIBUTING.rst
39+
s.move(templated_files / 'CONTRIBUTING.rst')
40+
3841
# ----------------------------------------------------------------------------
3942
# Samples templates
4043
# ----------------------------------------------------------------------------

0 commit comments

Comments
 (0)