@@ -9,342 +9,6 @@ Contributing
99
1010.. _Faster Pull Request Reviews : https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews
1111
12- .. contents :: Here are some guidelines for hacking on ``google-cloud-python``.
13-
14- ***************
15- Adding Features
16- ***************
17-
18- In order to add a feature to ``google-cloud-python ``:
19-
20- - The feature must be documented in both the API and narrative
21- documentation (in ``docs/ ``).
22-
23- - The feature must work fully on the following CPython versions: 2.7,
24- 3.5, 3.6, and 3.7 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- ****************************
31- Using a Development Checkout
32- ****************************
33-
34- You'll have to create a development environment to hack on
35- ``google-cloud-python ``, using a Git checkout:
36-
37- - While logged into your GitHub account, navigate to the
38- ``google-cloud-python `` `repo `_ on GitHub.
39-
40- - Fork and clone the ``google-cloud-python `` repository to your GitHub account by
41- clicking the "Fork" button.
42-
43- - Clone your fork of ``google-cloud-python `` from your GitHub account to your local
44- computer, substituting your account username and specifying the destination
45- as ``hack-on-google-cloud-python ``. E.g.::
46-
47- $ cd ${HOME}
48- $ git clone git@github.com:USERNAME/google-cloud-python.git hack-on-google-cloud-python
49- $ cd hack-on-google-cloud-python
50- # Configure remotes such that you can pull changes from the google-cloud-python
51- # repository into your local repository.
52- $ git remote add upstream git@github.com:googleapis/google-cloud-python.git
53- # fetch and merge changes from upstream into master
54- $ git fetch upstream
55- $ git merge upstream/master
56-
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-cloud-python
64-
65- Using ``nox ``
66- =============
67-
68- We use `nox <https://nox.readthedocs.io/en/latest/ >`__ to instrument our tests.
69-
70- You must install nox using Python 3.
71-
72- - To test your changes, go to the package directory and run ``nox ``::
73-
74- $ nox -s unit-2.7
75- $ nox -s unit-3.7
76- $ ...
77-
78- .. note::
79-
80- The unit tests and system tests are contained in the individual
81- ``noxfile.py`` files in each directory; substitute ``datastore`` in the
82- example above with the package of your choice.
83-
84-
85- Alternatively, you can just navigate directly to the package you are
86- currently developing and run tests there::
87-
88- $ export GIT_ROOT=$(pwd)
89- $ cd ${GIT_ROOT}/datastore/
90- $ nox -s unit-3.7
91-
92- .. nox: https://pypi.org/project/nox-automation/
93-
94-
95- ========================================
96-
97- - As mentioned previously, using ``setuptools `` in `develop mode `_
98- or a ``pip `` `editable install `_ is not possible with this
99- library. This is because this library uses `namespace packages `_.
100- For context see `Issue #2316 `_ and the relevant `PyPA issue `_.
101-
102- Since ``editable `` / ``develop `` mode can't be used, packages
103- need to be installed directly. Hence your changes to the source
104- tree don't get incorporated into the **already installed **
105- package.
106-
107- .. _namespace packages : https://www.python.org/dev/peps/pep-0420/
108- .. _Issue #2316 : https://github.com/GoogleCloudPlatform/google-cloud-python/issues/2316
109- .. _PyPA issue : https://github.com/pypa/packaging-problems/issues/12
110- .. _develop mode : https://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode
111- .. _editable install : https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs
112-
113- *****************************************
114- I'm getting weird errors... Can you help?
115- *****************************************
116-
117- If the error mentions ``Python.h `` not being found,
118- install ``python-dev `` and try again.
119- On Debian/Ubuntu::
120-
121- $ sudo apt-get install python-dev
122-
123- ************
124- Coding Style
125- ************
126-
127- - We use the automatic code formatter ``black ``. You can run it using
128- the nox session ``blacken ``. This will eliminate many lint errors.
129-
130- $ nox -s blacken
131-
132- - PEP8 compliance is required, with exceptions defined in the linter configuration.
133- You can test for non-compliant code via::
134-
135- $ nox -s lint
136-
137- - In order to make ``nox -s lint `` run faster, you can set some environment
138- variables::
139-
140- export GOOGLE_CLOUD_TESTING_REMOTE="upstream"
141- export GOOGLE_CLOUD_TESTING_BRANCH="master"
142-
143- By doing this, you are specifying the location of the most up-to-date
144- version of ``google-cloud-python ``. The suggested remote name ``upstream ``
145- should point to the official ``googleapis `` checkout and the
146- the branch should be the main branch on that remote (``master ``).
147-
148- Exceptions to PEP8:
149-
150- - Many unit tests use a helper method, ``_call_fut `` ("FUT" is short for
151- "Function-Under-Test"), which is PEP8-incompliant, but more readable.
152- Some also use a local variable, ``MUT `` (short for "Module-Under-Test").
153-
154- *************************
155- Commit Message Convention
156- *************************
157-
158- We use `Conventional Commits `_ as a convention for writing commit messages.
159- It provides an easy set of rules for creating an explicit commit history.
160-
161- .. _Conventional Commits : https://www.conventionalcommits.org/
162-
163- ********************
164- Running System Tests
165- ********************
166-
167- - To run system tests for a given package, go to the package directory
168- and execute::
169-
170- $ nox -s system-3.7
171- $ nox -s system-2.7
172-
173- .. note ::
174-
175- System tests are only configured to run under Python 2.7 and
176- Python 3.7. For expediency, we do not run them in older versions
177- of Python 3.
178-
179- This alone will not run the tests. You'll need to change some local
180- auth settings and change some configuration in your project to
181- run all the tests.
182-
183- - System tests will be run against an actual project and
184- so you'll need to provide some environment variables to facilitate
185- authentication to your project:
186-
187- - ``GOOGLE_APPLICATION_CREDENTIALS ``: The path to a JSON key file;
188- Such a file can be downloaded directly from the developer's console by clicking
189- "Generate new JSON key". See private key
190- `docs <https://cloud.google.com/storage/docs/authentication#generating-a-private-key >`__
191- for more details.
192-
193- - In order for Logging system tests to work, the Service Account
194- will also have to be made a project ``Owner ``. This can be changed under
195- "IAM & Admin". Additionally, ``cloud-logs@google.com `` must be given
196- ``Editor `` permissions on the project.
197-
198- - Once you have downloaded your json keys, set the environment variable
199- ``GOOGLE_APPLICATION_CREDENTIALS `` to the absolute path of the json file::
200-
201- $ export GOOGLE_APPLICATION_CREDENTIALS="/Users/<your_username>/path/to/app_credentials.json"
202-
203- - For datastore tests, you'll need to create composite
204- `indexes <https://cloud.google.com/datastore/docs/tools/indexconfig >`__
205- with the ``gcloud `` command line
206- `tool <https://developers.google.com/cloud/sdk/gcloud/ >`__::
207-
208- # Install the app (App Engine Command Line Interface) component.
209- $ gcloud components install app-engine-python
210-
211- # Authenticate the gcloud tool with your account.
212- $ GOOGLE_APPLICATION_CREDENTIALS="path/to/app_credentials.json"
213- $ gcloud auth activate-service-account \
214- > --key-file=${GOOGLE_APPLICATION_CREDENTIALS}
215-
216- # Create the indexes
217- $ gcloud datastore indexes create datastore/tests/system/index.yaml
218-
219- - For datastore query tests, you'll need stored data in your dataset.
220- To populate this data, run::
221-
222- $ python datastore/tests/system/utils/populate_datastore.py
223-
224- - If you make a mistake during development (i.e. a failing test that
225- prevents clean-up) you can clear all system test data from your
226- datastore instance via::
227-
228- $ python datastore/tests/system/utils/clear_datastore.py
229-
230-
231- ******************************
232- Running Generated Sample Tests
233- ******************************
234-
235- - To run system tests for a given package, go to the package directory
236- and execute::
237-
238- $ nox -s samples
239-
240- .. note ::
241-
242- Generated sample tests require the ``sample-tester `` commamd line
243- `tool <https://sample-tester.readthedocs.io> `.
244-
245- - Generated sample tests will be run against an actual project and
246- so you'll need to provide some environment variables to facilitate
247- authentication to your project (See: Running System Tests)
248-
249-
250- *************
251- Test Coverage
252- *************
253-
254- - The codebase *must * have 100% test statement coverage after each commit.
255- You can test coverage via ``nox -s cover ``.
256-
257- ******************************************************
258- Documentation Coverage and Building HTML Documentation
259- ******************************************************
260-
261- If you fix a bug, and the bug requires an API or behavior modification, all
262- documentation in this package which references that API or behavior must be
263- changed to reflect the bug fix, ideally in the same commit that fixes the bug
264- or adds the feature.
265-
266- To build and review docs go to the package directory and execute::
267-
268- $ nox -s docs
269-
270- #. Open the ``docs/_build/html/index.html `` file to see the resulting HTML
271- rendering.
272-
273- ********************************************
274- Note About ``README `` as it pertains to PyPI
275- ********************************************
276-
277- The `description on PyPI `_ for the project comes directly from the
278- ``README ``. Due to the reStructuredText (``rst ``) parser used by
279- PyPI, relative links which will work on GitHub (e.g. ``CONTRIBUTING.rst ``
280- instead of
281- ``https://github.com/GoogleCloudPlatform/google-cloud-python/blob/master/CONTRIBUTING.rst ``)
282- may cause problems creating links or rendering the description.
283-
284- .. _description on PyPI : https://pypi.org/project/google-cloud/
285-
286- **********************
287- Kokoro Configuration
288- **********************
289-
290- Build scripts and configurations are in the ``.kokoro `` directory.
291-
292-
293- *************************
294- Supported Python Versions
295- *************************
296-
297- We support:
298-
299- - `Python 3.5 `_
300- - `Python 3.6 `_
301- - `Python 3.7 `_
302-
303- .. _Python 3.5 : https://docs.python.org/3.5/
304- .. _Python 3.6 : https://docs.python.org/3.6/
305- .. _Python 3.7 : https://docs.python.org/3.7/
306-
307-
308- Supported versions can be found in our ``noxfile.py `` `config `_.
309-
310- .. _config : https://github.com/googleapis/google-cloud-python/blob/master/noxfile.py
311-
312- We explicitly decided not to support `Python 2.5 `_ due to `decreased usage `_
313- and lack of continuous integration `support `_.
314-
315- .. _Python 2.5 : https://docs.python.org/2.5/
316- .. _decreased usage : https://caremad.io/2013/10/a-look-at-pypi-downloads/
317- .. _support : https://blog.travis-ci.com/2013-11-18-upcoming-build-environment-updates/
318-
319- We have `dropped 2.6 `_ as a supported version as well since Python 2.6 is no
320- longer supported by the core development team.
321-
322- Python 2.7 support is deprecated. All code changes should maintain Python 2.7 compatibility until January 1, 2020.
323-
324- We also explicitly decided to support Python 3 beginning with version
325- 3.5. Reasons for this include:
326-
327- - Encouraging use of newest versions of Python 3
328- - Taking the lead of `prominent `_ open-source `projects `_
329- - `Unicode literal support `_ which allows for a cleaner codebase that
330- works in both Python 2 and Python 3
331-
332- .. _prominent : https://docs.djangoproject.com/en/1.9/faq/install/#what-python-version-can-i-use-with-django
333- .. _projects : http://flask.pocoo.org/docs/0.10/python3/
334- .. _Unicode literal support : https://www.python.org/dev/peps/pep-0414/
335- .. _dropped 2.6 : https://github.com/googleapis/google-cloud-python/issues/995
336-
337- **********
338- Versioning
339- **********
340-
341- This library follows `Semantic Versioning `_.
342-
343- .. _Semantic Versioning : http://semver.org/
344-
345- Some packages are currently in major version zero (``0.y.z ``), which means that
346- anything may change at any time and the public API should not be considered
347- stable.
34812
34913******************************
35014Contributor License Agreements
0 commit comments