1############
2Contributing
3############
4
5#. **Please sign one of the contributor license agreements below.**
6#. Fork the repo, develop and test your code changes, add docs.
7#. Make sure that your commit messages clearly describe the changes.
8#. Send a pull request. (Please Read: `Faster Pull Request Reviews`_)
9
10.. _Faster Pull Request Reviews: https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews
11
12.. contents:: Here are some guidelines for hacking on the Google Cloud Client libraries.
13
14***************
15Adding Features
16***************
17
18In order to add a feature:
19
20- The feature must be documented in both the API and narrative
21  documentation.
22
23- The feature must work fully on the following CPython versions:
24  3.6, 3.7, 3.8, 3.9, and 3.10 on both UNIX and Windows.
25
26- The feature must not add unnecessary dependencies (where
27  "unnecessary" is of course subjective, but new dependencies should
28  be discussed).
29
30****************************
31Using a Development Checkout
32****************************
33
34You'll have to create a development environment using a Git checkout:
35
36- While logged into your GitHub account, navigate to the
37  ``python-api-core`` `repo`_ on GitHub.
38
39- Fork and clone the ``python-api-core`` repository to your GitHub account by
40  clicking the "Fork" button.
41
42- Clone your fork of ``python-api-core`` from your GitHub account to your local
43  computer, substituting your account username and specifying the destination
44  as ``hack-on-python-api-core``.  E.g.::
45
46   $ cd ${HOME}
47   $ git clone [email protected]:USERNAME/python-api-core.git hack-on-python-api-core
48   $ cd hack-on-python-api-core
49   # Configure remotes such that you can pull changes from the googleapis/python-api-core
50   # repository into your local repository.
51   $ git remote add upstream [email protected]:googleapis/python-api-core.git
52   # fetch and merge changes from upstream into main
53   $ git fetch upstream
54   $ git merge upstream/main
55
56Now your local repo is set up such that you will push changes to your GitHub
57repo, from which you can submit a pull request.
58
59To work on the codebase and run the tests, we recommend using ``nox``,
60but you can also use a ``virtualenv`` of your own creation.
61
62.. _repo: https://github.com/googleapis/python-api-core
63
64Using ``nox``
65=============
66
67We use `nox <https://nox.readthedocs.io/en/latest/>`__ to instrument our tests.
68
69- To test your changes, run unit tests with ``nox``::
70    $ nox -s unit
71
72- To run a single unit test::
73
74    $ nox -s unit-3.10 -- -k <name of test>
75
76
77  .. note::
78
79    The unit tests tests are described in the ``noxfile.py`` files
80    in each directory.
81
82.. nox: https://pypi.org/project/nox/
83
84*****************************************
85I'm getting weird errors... Can you help?
86*****************************************
87
88If the error mentions ``Python.h`` not being found,
89install ``python-dev`` and try again.
90On Debian/Ubuntu::
91
92  $ sudo apt-get install python-dev
93
94************
95Coding Style
96************
97- We use the automatic code formatter ``black``. You can run it using
98  the nox session ``blacken``. This will eliminate many lint errors. Run via::
99
100   $ nox -s blacken
101
102- PEP8 compliance is required, with exceptions defined in the linter configuration.
103  If you have ``nox`` installed, you can test that you have not introduced
104  any non-compliant code via::
105
106   $ nox -s lint
107
108- In order to make ``nox -s lint`` run faster, you can set some environment
109  variables::
110
111   export GOOGLE_CLOUD_TESTING_REMOTE="upstream"
112   export GOOGLE_CLOUD_TESTING_BRANCH="main"
113
114  By doing this, you are specifying the location of the most up-to-date
115  version of ``python-api-core``. The the suggested remote name ``upstream``
116  should point to the official ``googleapis`` checkout and the
117  the branch should be the main branch on that remote (``main``).
118
119- This repository contains configuration for the
120  `pre-commit <https://pre-commit.com/>`__ tool, which automates checking
121  our linters during a commit.  If you have it installed on your ``$PATH``,
122  you can enable enforcing those checks via:
123
124.. code-block:: bash
125
126   $ pre-commit install
127   pre-commit installed at .git/hooks/pre-commit
128
129Exceptions to PEP8:
130
131- Many unit tests use a helper method, ``_call_fut`` ("FUT" is short for
132  "Function-Under-Test"), which is PEP8-incompliant, but more readable.
133  Some also use a local variable, ``MUT`` (short for "Module-Under-Test").
134
135
136*************
137Test Coverage
138*************
139
140- The codebase *must* have 100% test statement coverage after each commit.
141  You can test coverage via ``nox -s cover``.
142
143******************************************************
144Documentation Coverage and Building HTML Documentation
145******************************************************
146
147If you fix a bug, and the bug requires an API or behavior modification, all
148documentation in this package which references that API or behavior must be
149changed to reflect the bug fix, ideally in the same commit that fixes the bug
150or adds the feature.
151
152Build the docs via:
153
154   $ nox -s docs
155
156*************************
157Samples and code snippets
158*************************
159
160Code samples and snippets live in the `samples/` catalogue. Feel free to
161provide more examples, but make sure to write tests for those examples.
162Each folder containing example code requires its own `noxfile.py` script
163which automates testing. If you decide to create a new folder, you can
164base it on the `samples/snippets` folder (providing `noxfile.py` and
165the requirements files).
166
167The tests will run against a real Google Cloud Project, so you should
168configure them just like the System Tests.
169
170- To run sample tests, you can execute::
171
172   # Run all tests in a folder
173   $ cd samples/snippets
174   $ nox -s py-3.8
175
176   # Run a single sample test
177   $ cd samples/snippets
178   $ nox -s py-3.8 -- -k <name of test>
179
180********************************************
181Note About ``README`` as it pertains to PyPI
182********************************************
183
184The `description on PyPI`_ for the project comes directly from the
185``README``. Due to the reStructuredText (``rst``) parser used by
186PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst``
187instead of
188``https://github.com/googleapis/python-api-core/blob/main/CONTRIBUTING.rst``)
189may cause problems creating links or rendering the description.
190
191.. _description on PyPI: https://pypi.org/project/google-api-core
192
193
194*************************
195Supported Python Versions
196*************************
197
198We support:
199
200-  `Python 3.6`_
201-  `Python 3.7`_
202-  `Python 3.8`_
203-  `Python 3.9`_
204-  `Python 3.10`_
205
206.. _Python 3.6: https://docs.python.org/3.6/
207.. _Python 3.7: https://docs.python.org/3.7/
208.. _Python 3.8: https://docs.python.org/3.8/
209.. _Python 3.9: https://docs.python.org/3.9/
210.. _Python 3.10: https://docs.python.org/3.10/
211
212
213Supported versions can be found in our ``noxfile.py`` `config`_.
214
215.. _config: https://github.com/googleapis/python-api-core/blob/main/noxfile.py
216
217
218We also explicitly decided to support Python 3 beginning with version 3.6.
219Reasons for this include:
220
221-  Encouraging use of newest versions of Python 3
222-  Taking the lead of `prominent`_ open-source `projects`_
223-  `Unicode literal support`_ which allows for a cleaner codebase that
224   works in both Python 2 and Python 3
225
226.. _prominent: https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django
227.. _projects: http://flask.pocoo.org/docs/0.10/python3/
228.. _Unicode literal support: https://www.python.org/dev/peps/pep-0414/
229
230**********
231Versioning
232**********
233
234This library follows `Semantic Versioning`_.
235
236.. _Semantic Versioning: http://semver.org/
237
238Some packages are currently in major version zero (``0.y.z``), which means that
239anything may change at any time and the public API should not be considered
240stable.
241
242******************************
243Contributor License Agreements
244******************************
245
246Before we can accept your pull requests you'll need to sign a Contributor
247License Agreement (CLA):
248
249- **If you are an individual writing original source code** and **you own the
250  intellectual property**, then you'll need to sign an
251  `individual CLA <https://developers.google.com/open-source/cla/individual>`__.
252- **If you work for a company that wants to allow you to contribute your work**,
253  then you'll need to sign a
254  `corporate CLA <https://developers.google.com/open-source/cla/corporate>`__.
255
256You can sign these electronically (just scroll to the bottom). After that,
257we'll be able to accept your pull requests.
258