Document the Debian/Ubuntu opentracing build failure

docs/contributing.rst

@@ -394,6 +394,25 @@ dependencies, so install these:
     $ pip install -U -r requirements/test.txt
     $ pip install -U -r requirements/default.txt
 
+.. note::
+
+    Install these into a virtualenv.  On Debian and Ubuntu, installing them
+    into the system Python can fail while building :pypi:`opentracing` (pulled
+    in by :file:`requirements/test.txt`) with::
+
+        AttributeError: install_layout
+
+    :pypi:`opentracing` publishes no wheel, so pip builds it from the sdist
+    through the legacy :file:`setup.py` path using whatever setuptools is
+    already installed -- and Debian's packaged ``python3-setuptools`` patches
+    its ``install_lib`` command to read an ``install_layout`` option that the
+    ``install`` command it runs against does not define.
+
+    A virtualenv gets an unpatched setuptools and builds it fine.  If you must
+    install into the system Python, either upgrade setuptools in place
+    (``pip install -U setuptools``) or build that one package in an isolated
+    environment (``pip install --use-pep517 opentracing``).
+
 After installing the dependencies required, you can now execute
 the test suite by calling :pypi:`py.test <pytest`:
 

requirements/extras/opentracing.txt

@@ -1 +1,6 @@
+# 2.4.0 is the latest release and publishes no wheel, so pip builds it from
+# the sdist through the legacy setup.py path, using whatever setuptools is
+# already installed.  Debian and Ubuntu's packaged python3-setuptools fails
+# that build with "AttributeError: install_layout"; installing into a
+# virtualenv avoids it.  See "Running the test suite" in docs/contributing.rst.
 opentracing>=1.3.0,<=2.4.0