docs: explain migration from coverage run to pytest-cov

AUTHORS.rst

@@ -67,3 +67,4 @@ Authors
 * Ofek Lev - https://github.com/ofek
 * Art Pelling - https://github.com/artpelling
 * Markéta Machová - https://github.com/MeggyCal
+* xuu33030 - https://github.com/xuu33030

CHANGELOG.rst

@@ -2,6 +2,12 @@
 Changelog
 =========
 
+Unreleased
+----------
+
+* Document the import-path difference between ``coverage run -m pytest`` and ``pytest --cov`` for users migrating from coverage.py.
+  Contributed by xuu33030.
+
 7.1.0 (2026-03-21)
 ------------------
 

README.rst

@@ -57,6 +57,18 @@ This plugin provides coverage functionality as a pytest plugin. Compared to just
 All features offered by the coverage package should work, either through pytest-cov's command line options or
 through coverage's config file.
 
+Migrating from coverage.py
+--------------------------
+
+``coverage run -m pytest`` and ``pytest --cov`` do not necessarily import code the same way. The former starts pytest with
+``python -m``, which adds the current working directory to ``sys.path``. The latter uses the ``pytest`` command, which does
+not add it automatically. If coverage drops unexpectedly after switching, check that the package under test is installed
+in your environment (for example, with ``pip install -e .``) rather than relying on the working directory being importable.
+Run ``pytest --cov=myproj tests/`` from the same environment to confirm that tests still import your package.
+
+For subprocess coverage, pytest-cov 7 no longer installs the ``.pth`` file used by earlier releases; see
+`Upgrading from pytest-cov 6.3`_ below for the replacement.
+
 * Free software: MIT license
 
 Installation