Prepare non-primary Django tests in zuul jobs

We already have a template 'horizon-non-primary-django-jobs'
to test horizon and plugins with non-primary django versions,
but we still need to update tox.ini in all horizon plugins
whenever we change Django versions used.

This commit prepares per-Django environment in the zuul job.

Per-Django tox environments like py3-{dj111,dj20,dj22} are
no longer needed. It would be a big merit that we will no longer
need to update tox.ini in all horizon plugins.

The downside is that we do not provide a convenient way to
test it locally, but I think it can be covered in the document.

Change-Id: I726b19130ee9e7d06eb33231071c2673cfd3a49f

.zuul.yaml

@@ -10,20 +10,39 @@
       - ^openstack_auth/locale/.*$
 
 - job:
-    name: horizon-openstack-tox-python3-django111
+    name: horizon-tox-python3-django
+    abstract: true
     parent: horizon-openstack-tox-base
+    description: |
+      Run tox with different Django version.
+
+      .. zuul:jobvar: tox_envlist
+
+         Which tox environment to run
+
+      .. zuul:jobvar: django_version
+
+         Django version to be used.
+         pip version specifier like ``>=1.11,<2.0`` should be passed.
+
+    pre-run: playbooks/horizon-tox-django/pre.yaml
+    run: playbooks/horizon-tox-django/run.yaml
     vars:
-      tox_envlist: py3-dj111
+      tox_envlist: py36
     required-projects:
       - name: openstack/horizon
 
 - job:
-    name: horizon-openstack-tox-python3-django22
-    parent: horizon-openstack-tox-base
+    name: horizon-tox-python3-django111
+    parent: horizon-tox-python3-django
     vars:
-      tox_envlist: py3-dj22
-    required-projects:
-      - name: openstack/horizon
+      django_version: '>=1.11,<2.0'
+
+- job:
+    name: horizon-tox-python3-django22
+    parent: horizon-tox-python3-django
+    vars:
+      django_version: '>=2.2,<3.0'
 
 - job:
     name: horizon-selenium-headless
@@ -154,12 +173,12 @@
       Run unit tests with non-primary Django versions.
     check:
       jobs:
-        - horizon-openstack-tox-python3-django111
-        - horizon-openstack-tox-python3-django22
+        - horizon-tox-python3-django111
+        - horizon-tox-python3-django22
     gate:
       jobs:
-        - horizon-openstack-tox-python3-django111
-        - horizon-openstack-tox-python3-django22
+        - horizon-tox-python3-django111
+        - horizon-tox-python3-django22
 
 - project:
     templates:

doc/source/contributor/topics/testing.rst

@@ -229,6 +229,48 @@ Tips and tricks
     +        },
              'django.db.backends': {
 
+Testing with different Django versions
+--------------------------------------
+
+Horizon supports multiple Django versions and our CI tests proposed patches
+with various supported Django versions. The corresponding job names are like
+``horizon-tox-python3-django111``.
+
+You can know which tox env and django version are used by checking
+``tox_envlist`` and ``django_version`` of the corresponding job definition
+in ``.zuul.yaml``.
+
+To test it locally, you need some extra steps.
+Here is an example where ``tox_envlist`` is ``py36`` and
+``django_version`` is ``>=1.11,<2.0``.
+
+.. code:: console
+
+   $ tox -e py36 --notest -r
+   $ .tox/py36/bin/python -m pip install 'django>=1.11,<2.0'
+   $ tox -e py36
+
+.. note::
+
+   - ``-r`` in the first command recreates the tox environment.
+     Omit it if you know what happens.
+   - We usually need to quote the django version in the pip command-line
+     in most shells to escape interpretations by the shell.
+
+To check the django version installed in your tox env, run:
+
+.. code:: console
+
+   $ .tox/py36/bin/python -m pip freeze | grep Django
+   Django==1.11.27
+
+To reset the tox env used for testing with different Django version
+to the regular tox env, run ``tox`` command with ``-r`` to recreate it.
+
+.. code:: console
+
+   $ tox -e py36 -r
+
 Coverage reports
 ----------------
 

playbooks/horizon-tox-django/pre.yaml

@@ -0,0 +1,11 @@
+# The base contents come from zuul-jobs/playbooks/tox/run.yaml
+- hosts: all
+  roles:
+    - revoke-sudo
+    - role: tox
+      vars:
+        # Do not run actual tests now as we would like to install
+        # a different version of django.
+        tox_extra_args: "-vv --notest"
+        tox_install_siblings: true
+    - ensure-django

playbooks/horizon-tox-django/run.yaml

@@ -0,0 +1,7 @@
+# The base contents come from zuul-jobs/playbooks/tox/run.yaml
+- hosts: all
+  roles:
+    # siblings modules are already handled, so we can skip it.
+    - role: tox
+      vars:
+        tox_install_siblings: false

roles/ensure-django/defaults/main.yaml

@@ -0,0 +1,3 @@
+django_version: ""
+tox_envlist: venv
+zuul_work_dir: "{{ zuul.project.src_dir }}"

roles/ensure-django/tasks/main.yaml

@@ -0,0 +1,4 @@
+- name: "Install Django"
+  command: ".tox/{{ tox_envlist }}/bin/python -m pip install django{{ django_version }}"
+  args:
+    chdir: "{{ zuul_work_dir }}"

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 minversion = 3.1
-envlist = pep8,py36,py37,py3-dj{111,21,22},releasenotes,npm
+envlist = pep8,py36,py37,releasenotes,npm
 skipsdist = True
 # Automatic envs (pyXX) will only use the python version appropriate to that
 # env and ignore basepython inherited from [testenv] if we set
@@ -24,9 +24,6 @@ deps =
   -r{toxinidir}/test-requirements.txt
   -r{toxinidir}/requirements.txt
 commands =
-  dj111: pip install django>=1.11,<2.0
-  dj21: pip install django>=2.1,<2.2
-  dj22: pip install django>=2.2,<2.3
   find . -type f -name "*.pyc" -delete
   bash {toxinidir}/tools/unit_tests.sh {envpython} {toxinidir} {posargs}