Review README

Small review of README

  Add Documentation section

  Minor changes

  Fix a bug by adding an admonishment

Also synced tox/pip boilerplate in order to include:
* https://github.com/openstack-charmers/release-tools/pull/156
* https://github.com/openstack-charmers/release-tools/pull/157

Closes-Bug: #1881171
Change-Id: I405e8f2692be76695ac3f57a7618deae98e45225
Co-authored-by: Aurelien Lourot <aurelien.lourot@canonical.com>

.zuul.yaml

@@ -1,5 +1,4 @@
 - project:
     templates:
-      - python35-charm-jobs
-      - openstack-python3-ussuri-jobs
+      - openstack-python3-charm-jobs
       - openstack-cover-jobs

pip.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+#
+# This file is managed centrally by release-tools and should not be modified
+# within individual charm repos.  See the 'global' dir contents for available
+# choices of tox.ini for OpenStack Charms:
+#     https://github.com/openstack-charmers/release-tools
+#
+# setuptools 58.0 dropped the support for use_2to3=true which is needed to
+# install blessings (an indirect dependency of charm-tools).
+#
+# More details on the beahvior of tox and virtualenv creation can be found at
+# https://github.com/tox-dev/tox/issues/448
+#
+# This script is wrapper to force the use of the pinned versions early in the
+# process when the virtualenv was created and upgraded before installing the
+# depedencies declared in the target.
+pip install 'pip<20.3' 'setuptools<50.0.0'
+pip "$@"

src/README.md

@@ -33,19 +33,26 @@ their descriptions and default values.
 
 ## Deployment
 
-To deploy a MySQL 8 Router:
+To deploy a MySQL 8 Router for joining, say, Keystone to the cloud database:
 
-    juju deploy mysql-router
+    juju deploy mysql-router keystone-mysql-router
 
-Add a relation to a principle application (via the [shared-db][shared-db]
+> **Note**: The mysql-router application is typically given a name that
+  corresponds to the associated principle application.
+
+Add a relation to the principle application (via the [shared-db][shared-db]
 endpoint):
 
-    juju add-relation keystone:shared-db mysql-router:shared-db
+    juju add-relation keystone:shared-db keystone-mysql-router:shared-db
 
 Then add a relation to the mysql-innodb-cluster application (via the
 [db-router][db-router] endpoint):
 
-    juju add-relation msyql-router:db-router mysql-innodb-cluster:db-router
+    juju add-relation keystone-msyql-router:db-router mysql-innodb-cluster:db-router
+
+> **Important**: When network spaces are used, the mysql-router and
+  mysql-innodb-cluster charms must be configured such that the 'db-router'
+  endpoint is bound to the same space.
 
 Scale out is accomplished by adding units to the principle application:
 
@@ -59,22 +66,29 @@ Scale out is accomplished by adding units to the principle application:
 
 This section lists Juju [actions][juju-docs-actions] supported by the charm.
 Actions allow specific operations to be performed on a per-unit basis. To
-display action descriptions run `juju actions mysql-router`. If the
+display action descriptions run `juju actions --schema mysql-router`. If the
 charm is not deployed then see file `actions.yaml`.
 
 * `stop-mysqlrouter`
 * `start-mysqlrouter`
 * `restart-mysqlrouter`
 
+# Documentation
+
+The OpenStack Charms project maintains two documentation guides:
+
+* [OpenStack Charm Guide][cg]: for project information, including development
+  and support notes
+* [OpenStack Charms Deployment Guide][cdg]: for charm usage information
+
 # Bugs
 
 Please report bugs on [Launchpad][lp-bugs-charm-mysql-router].
 
-For general charm questions refer to the [OpenStack Charm Guide][cg].
-
 <!-- LINKS -->
 
 [cg]: https://docs.openstack.org/charm-guide
+[cdg]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide
 [lp-bugs-charm-mysql-router]: https://bugs.launchpad.net/charm-mysql-router/+filebug
 [juju-docs-actions]: https://jaas.ai/docs/actions
 [percona-cluster-charm]: https://jaas.ai/percona-cluster

src/tox.ini

@@ -22,12 +22,12 @@ skip_missing_interpreters = False
 requires = pip < 20.3
            virtualenv < 20.0
 # NOTE: https://wiki.canonical.com/engineering/OpenStack/InstallLatestToxOnOsci
-minversion = 3.2.0
+minversion = 3.18.0
 
 [testenv]
 setenv = VIRTUAL_ENV={envdir}
          PYTHONHASHSEED=0
-whitelist_externals = juju
+allowlist_externals = juju
 passenv = HOME TERM CS_* OS_* TEST_*
 deps = -r{toxinidir}/test-requirements.txt
 install_command =

tox.ini

@@ -11,6 +11,21 @@ envlist = pep8,py3
 sitepackages = False
 # NOTE: Avoid false positives by not skipping missing interpreters.
 skip_missing_interpreters = False
+# NOTES:
+# * We avoid the new dependency resolver by pinning pip < 20.3, see
+#   https://github.com/pypa/pip/issues/9187
+# * Pinning dependencies requires tox >= 3.2.0, see
+#   https://tox.readthedocs.io/en/latest/config.html#conf-requires
+# * It is also necessary to pin virtualenv as a newer virtualenv would still
+#   lead to fetching the latest pip in the func* tox targets, see
+#   https://stackoverflow.com/a/38133283
+requires =
+  pip < 20.3
+  virtualenv < 20.0
+  setuptools<50.0.0
+
+# NOTE: https://wiki.canonical.com/engineering/OpenStack/InstallLatestToxOnOsci
+minversion = 3.18.0
 
 [testenv]
 setenv = VIRTUAL_ENV={envdir}
@@ -21,7 +36,7 @@ setenv = VIRTUAL_ENV={envdir}
          JUJU_REPOSITORY={toxinidir}/build
 passenv = http_proxy https_proxy INTERFACE_PATH LAYER_PATH JUJU_REPOSITORY
 install_command =
-  pip install {opts} {packages}
+  {toxinidir}/pip.sh install {opts} {packages}
 deps =
     -r{toxinidir}/requirements.txt