From 7015f597e374e1f66d929da45ec08775af113e15 Mon Sep 17 00:00:00 2001
From: Jason Madden <jamadden@gmail.com>
Date: Fri, 2 Feb 2018 09:29:42 -0600
Subject: [PATCH] Document that PyPy does not work with mysqlconnector and
 remove it from the matrix.

---
 .travis.yml     |  7 +++++--
 CHANGES.rst     |  4 +++-
 doc/install.rst | 50 ++++++++++++++++++++++++++++++++-----------------
 3 files changed, 41 insertions(+), 20 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 7650cd8..0838898 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -19,8 +19,11 @@ matrix:
         - RS_MY_DRIVER="C MySQL Connector/Python"
     - python: 3.6
       env: ENV=mysqlconnector
-    - python: pypy
-      env: ENV=mysqlconnector
+
+    # PyPy 5.8.0 is knonwn to be broken. Check again
+    # when Travis updates.
+    #- python: pypy
+    #  env: ENV=mysqlconnector
 
     - python: 3.6
       env: ENV=mysql
diff --git a/CHANGES.rst b/CHANGES.rst
index f476188..c0557e8 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -10,7 +10,9 @@
   CFFI compilation environment. Fixes :issue:`187`, reported by
   Johannes Raggam.
 
-- Test with MySQL Connector/Python 8.0.6, up from 2.1.5.
+- Test with MySQL Connector/Python 8.0.6, up from 2.1.5. Note that
+  PyPy 5.8.0 is known to *not* work with MySQL Connector/Python
+  (although PyPy 5.6.0 did).
 
 
 2.1a2 (2017-04-15)
diff --git a/doc/install.rst b/doc/install.rst
index dbecc61..839a76f 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -49,27 +49,31 @@ PyMySQL, MySQL Connector/Python  and pg8000 are also known to work.
 On PyPy, install psycopg2cffi 2.7.4+ or PyMySQL 0.6.6+ (PyPy will
 generally work with psycopg2 and mysqlclient, but it will be *much*
 slower; in contrast, pg8000 performs nearly as well. cx_Oracle is
-untested on PyPy).
+untested on PyPy). MySQL Connector/Python is explicitly known *not* to
+work on recent versions of PyPy. [#f1]_
 
 Here's a table of known (tested) working adapters; adapters **in
 bold** are the recommended adapter.
 
-+----------+---------------------+---------------------+--------------+
-| Platform |  MySQL              |   PostgreSQL        |  Oracle      |
-+==========+=====================+=====================+==============+
-| CPython2 |                     |  1. **psycopg2**    | **cx_Oracle**|
-|          | 1. **mysqlclient**  |  2. pg8000          |              |
-|          | 2. PyMySQL          |                     |              |
-|          | 3. umysqldb         |                     |              |
-|          | 4. MySQL Connector  |                     |              |
-+----------+---------------------+---------------------+--------------+
-| CPython3 | 1. **mysqlclient**  |  1. **psycopg2**    | **cx_Oracle**|
-|          | 2. PyMySQL          |  2. pg8000          |              |
-|          | 3. MySQL Connector  |                     |              |
-+----------+---------------------+---------------------+--------------+
-| PyPy     | 1. **PyMySQL**      | 1. **psycopg2cffi** |              |
-|          | 2. MySQL Connector  | 2.  pg8000          |              |
-+----------+---------------------+---------------------+--------------+
+.. table:: Tested Adapters
+   :widths: auto
+
+   +----------+---------------------+---------------------+--------------+
+   | Platform |  MySQL              |   PostgreSQL        |  Oracle      |
+   +==========+=====================+=====================+==============+
+   | CPython2 | 1. **mysqlclient**  |  1. **psycopg2**    | **cx_Oracle**|
+   |          | 2. PyMySQL          |  2. pg8000          |              |
+   |          | 3. umysqldb         |                     |              |
+   |          | 4. MySQL Connector  |                     |              |
+   |          |                     |                     |              |
+   +----------+---------------------+---------------------+--------------+
+   | CPython3 | 1. **mysqlclient**  |  1. **psycopg2**    | **cx_Oracle**|
+   |          | 2. PyMySQL          |  2. pg8000          |              |
+   |          | 3. MySQL Connector  |                     |              |
+   +----------+---------------------+---------------------+--------------+
+   | PyPy     | 1. **PyMySQL**      | 1. **psycopg2cffi** |              |
+   |          |                     | 2.  pg8000          |              |
+   +----------+---------------------+---------------------+--------------+
 
 
 mysqlclient, MySQL Connector/Python (without its C extension), pg8000
@@ -91,3 +95,15 @@ on CPython and PyPy, compatible with gevent).
 
 Once RelStorage is installed, it's time to :doc:`configure the database <configure-database>`
 you'll be using.
+
+.. rubric:: Footnotes
+
+.. [#f1] Broken tests `were observed
+         <https://travis-ci.org/zodb/relstorage/jobs/336589498#L912>`_
+         for PyPy2 5.8.0 using both Connector 2.1.5 and 8.0.6. `Tests
+         passed <https://travis-ci.org/zodb/relstorage/builds/245866051>`_
+         using PyPy2 5.6.0 and Connector 2.1.5. On the other hand,
+         CPython 2.7.14 and CPython 2.7.9 are tested to work with the
+         C extension, and CPython 3.6.0 and 3.6.3 have been tested to
+         work with the pure-Python extension (the same extension PyPy
+         would use).