Merge pull request #10007 from nicoddemus/importlib-docs

Author: nicoddemus

doc/en/explanation/goodpractices.rst

@@ -173,10 +173,9 @@ This layout prevents a lot of common pitfalls and has many benefits, which are b
 `blog post by Ionel Cristian Mărieș <https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure>`_.
 
 .. note::
-    The new ``--import-mode=importlib`` (see :ref:`import-modes`) doesn't have
+    The ``--import-mode=importlib`` option (see :ref:`import-modes`) does not have
     any of the drawbacks above because ``sys.path`` is not changed when importing
-    test modules, so users that run
-    into this issue are strongly encouraged to try it and report if the new option works well for them.
+    test modules, so users that run into this issue are strongly encouraged to try it.
 
     The ``src`` directory layout is still strongly recommended however.
 

doc/en/explanation/pythonpath.rst

@@ -45,10 +45,19 @@ these values:
 
 * ``importlib``: new in pytest-6.0, this mode uses :mod:`importlib` to import test modules. This gives full control over the import process, and doesn't require changing :py:data:`sys.path`.
 
-  For this reason this doesn't require test module names to be unique, but also makes test
-  modules non-importable by each other.
+  For this reason this doesn't require test module names to be unique.
+
+  One drawback however is that test modules are non-importable by each other. Also,  utility
+  modules in the tests directories are not automatically importable because the tests directory is no longer
+  added to :py:data:`sys.path`.
+
+  Initially we intended to make ``importlib`` the default in future releases, however it is clear now that
+  it has its own set of drawbacks so the default will remain ``prepend`` for the foreseeable future.
+
+.. seealso::
+
+    The :confval:`pythonpath` configuration variable.
 
-  We intend to make ``importlib`` the default in future releases, depending on feedback.
 
 ``prepend`` and ``append`` import modes scenarios
 -------------------------------------------------