From 4aedf1f7135b8c402005a15190e64b697b46d471 Mon Sep 17 00:00:00 2001
From: xuu33030 <268775543+xuu33030@users.noreply.github.com>
Date: Wed, 30 Sep 2026 01:29:12 +0800
Subject: [PATCH] docs: explain migration from coverage run to pytest-cov

---
 AUTHORS.rst   |  1 +
 CHANGELOG.rst |  6 ++++++
 README.rst    | 12 ++++++++++++
 3 files changed, 19 insertions(+)

diff --git a/AUTHORS.rst b/AUTHORS.rst
index 3291067a..710e9d98 100644
--- a/AUTHORS.rst
+++ b/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
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 919f3898..67e3b8ea 100644
--- a/CHANGELOG.rst
+++ b/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)
 ------------------
 
diff --git a/README.rst b/README.rst
index 23d9fdea..88d0b5b6 100644
--- a/README.rst
+++ b/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