diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 40b0aa6c4c..2b19390a48 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 @@ -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 -``` diff --git a/README.rst b/README.rst index 96c1d0bda2..78fc05fc41 100644 --- a/README.rst +++ b/README.rst @@ -53,30 +53,6 @@ dependencies. .. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ -Mac/Linux -~~~~~~~~~ - -.. code-block:: console - - pip install virtualenv - virtualenv - source /bin/activate - /bin/pip install python-spanner-django - /bin/pip install google-cloud-spanner - - -Windows -~~~~~~~ - -.. code-block:: console - - pip install virtualenv - virtualenv - \Scripts\activate - \Scripts\pip.exe install python-spanner-django - \Scripts\pip.exe install google-cloud-spanner - - Supported versions ~~~~~~~~~~~~~~~~~~ @@ -87,6 +63,10 @@ Both versions are long-term support (LTS) releases for the `Django project_`. The minimum required Python version is 3.6. +.. code:: shell + + pip3 install django==3.2 + Installing the package ~~~~~~~~~~~~~~~~~~~~~~ @@ -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: @@ -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 @@ -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. @@ -253,10 +230,12 @@ By participating in this project you agree to abide by its terms. See the `Code of Conduct `_ for more information. -LIMITATIONS ------------------ +Limitations +~~~~~~~~~~~ -Spanner has certain limitations of it's own and a full set of limitations are documented over `here `_ +Spanner has certain limitations of its own. The full set of limitations is documented +`here `__. It is recommended that you go through that list. -Django spanner has a set of limitations as well, please go through the `list `_. +Django spanner has a set of limitations as well, which you can find +`here `__. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 950bb65f28..9988ce2d87 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,7 +27,7 @@ For a list of all ``google-cloud-spanner-django`` releases: changelog Limitations ---------- +----------- .. toctree:: :maxdepth: 1