Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: typo fixes in readme #732

Merged
merged 4 commits into from Oct 28, 2021
Merged

docs: typo fixes in readme #732

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6309ea3
docs: typo fixes in readme
vi3k6i5 Oct 27, 2021
af85658
docs: fix underline in index.rst
vi3k6i5 Oct 27, 2021
15101aa
docs: change ref link to anonymous reference
vi3k6i5 Oct 27, 2021
0184194
docs: update contributing doc, remove stale commands related to tests
vi3k6i5 Oct 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
61 changes: 0 additions & 61 deletions CONTRIBUTING.md
View file
Open in desktop
@@ -1,8 +1,5 @@
# How to Contribute

We'd love to accept your patches and contributions to this project. There are
just a few small guidelines you need to follow.

## Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License
Expand All @@ -26,61 +23,3 @@ information on using pull requests.

This project follows [Google's Open Source Community
Guidelines](https://opensource.google/conduct/).

## Tests

### Functional tests
We have functional tests for individual components that can be run by
```shell
tox
```

### Django integration tests
We run full integration tests with continuous integration on Google Cloud Build with Kokoro.

The tests to be run are specified in file [django_test_apps.txt](./django_test_apps.txt)

There are 2 ways to run the tests:

#### django_test_suite.sh

This method requires an already existing Cloud Spanner instance.
Expected environment variables:

##### Environment variables
Variable|Description|Comment
---|---|---
`GOOGLE_APPLICATION_CREDENTIALS`|The Google Application Credentials file|For example `GOOGLE_APPLICATION_CREDENTIALS=~/Downloads/creds.json`
`PROJECT_ID`|The project id of the Google Application credentials being used|For example `PROJECT_ID=appdev-soda-spanner-staging`
`DJANGO_TEST_APPS`|The Django test suite apps to run|For example `DJANGO_TEST_APPS="basic i18n admin_views"`
`SPANNER_TEST_INSTANCE`|The Cloud Spanner instance to use, it MUST exist before running tests|For example `SPANNER_TEST_INSTANCE="django-tests"`
`DJANGO_TESTS_DIR`|The directory into which Django has been cloned to run the test suite|For example `DJANGO_TESTS_DIR=django_tests`

##### Example run
```shell
GOOGLE_APPLICATION_CREDENTIALS=~/Downloads/creds.json \
PROJECT_ID=appdev-soda DJANGO_TEST_APPS="expressions i18n" \
SPANNER_TEST_INSTANCE=django-tests ./django_tests_suite.sh
```

#### Parallelization script

This method shards tests over multiple builds, and over available cores.

##### Environment variables
To run the tests locally, you'll need the following environment variables.

Variable|Description|Comment
---|---|---
`GOOGLE_APPLICATION_CREDENTIALS`|The Google Application Credentials file|For example `GOOGLE_APPLICATION_CREDENTIALS=~/Downloads/creds.json`
`PROJECT_ID`|The project id of the Google Application credentials being used|For example `PROJECT_ID=appdev-soda-spanner-staging`
`DJANGO_WORKER_COUNT`|The number of parallel jobs to split the tests amongst|To get all the tests run by one process, use a cout of 1, so `DJANGO_WORKER_COUNT=1`
`DJANGO_WORKER_INDEX`|The zero based index of the parallel job number, to run tests, it is correlated with `DJANGO_WORKER_COUNT` and an offset to figure out which tests to run with this job|
`django_test_apps.txt`|The listing of Django apps to run|Set the apps you'd like to be run in parallel

##### Example run
```shell
GOOGLE_APPLICATION_CREDENTIALS=~/Downloads/creds.json \
PROJECT_ID=appdev-soda DJANGO_TEST_APPS="expressions i18n" \
DJANGO_WORKER_COUNT=1 DJANGO_WORKER_INDEX=0SPANNER_TEST_INSTANCE=django-tests ./bin/parallelize_tests_linux
```
51 changes: 15 additions & 36 deletions README.rst
View file
Open in desktop
Expand Up @@ -53,30 +53,6 @@ dependencies.
.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/


Mac/Linux
~~~~~~~~~

.. code-block:: console

pip install virtualenv
virtualenv <your-env>
source <your-env>/bin/activate
<your-env>/bin/pip install python-spanner-django
<your-env>/bin/pip install google-cloud-spanner


Windows
~~~~~~~

.. code-block:: console

pip install virtualenv
virtualenv <your-env>
<your-env>\Scripts\activate
<your-env>\Scripts\pip.exe install python-spanner-django
<your-env>\Scripts\pip.exe install google-cloud-spanner


Supported versions
~~~~~~~~~~~~~~~~~~

Expand All @@ -87,6 +63,10 @@ Both versions are long-term support (LTS) releases for the
`Django project<https://www.djangoproject.com/download/#supported-versions>_`.
The minimum required Python version is 3.6.

.. code:: shell

pip3 install django==3.2


Installing the package
~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -172,13 +152,10 @@ Please run:

$ python3 manage.py migrate

and that'll take a while to run. After this you should be able to see the tables and indices created in your Cloud Spanner console.
That'll take a while to run. After this you should be able to see the tables and indexes created in your Cloud Spanner console.

Now run your server
~~~~~~~~~~~~~~~~~~~
After those migrations are completed, that will be all. Please continue on with the guides.

Create an Django admin user
Create a Django admin user
~~~~~~~~~~~~~~~~~~~~~~~~~~~
First you’ll need to create a user who can login to the admin site. Run the following command:

Expand All @@ -199,7 +176,7 @@ which will then produce a prompt which will allow you to create your super user

Login as admin
~~~~~~~~~~~~~~
Let’s run the server
Now, run the server

.. code:: shell

Expand Down Expand Up @@ -241,8 +218,8 @@ Here is an example of how to add a row for Model Author, save it and later query
>>> qs1 = Author.objects.all().values("first_name", "last_name")


HOW TO CONTRIBUTE
-----------------
How to contribute
~~~~~~~~~~~~~~~~~

Contributions to this library are always welcome and highly encouraged.

Expand All @@ -253,10 +230,12 @@ By participating in this project you agree to abide by its terms. See the `Code
of Conduct <https://github.com/googleapis/python-spanner-django/blob/main/CODE_OF_CONDUCT.md>`_ for more information.


LIMITATIONS
-----------------
Limitations
~~~~~~~~~~~

Spanner has certain limitations of it's own and a full set of limitations are documented over `here <https://cloud.google.com/spanner/quotas#schema_limits>`_
Spanner has certain limitations of its own. The full set of limitations is documented
`here <https://cloud.google.com/spanner/quotas#schema_limits>`__.
It is recommended that you go through that list.

Django spanner has a set of limitations as well, please go through the `list <https://github.com/googleapis/python-spanner-django/blob/main/docs/limitations.rst>`_.
Django spanner has a set of limitations as well, which you can find
`here <https://github.com/googleapis/python-spanner-django/blob/main/docs/limitations.rst>`__.
2 changes: 1 addition & 1 deletion docs/index.rst
View file
Open in desktop
Expand Up @@ -27,7 +27,7 @@ For a list of all ``google-cloud-spanner-django`` releases:
changelog

Limitations
---------
-----------

.. toctree::
:maxdepth: 1
Expand Down