deprecated: the annotate command will be removed in a future version

4 files changed, 24 insertions, 2 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 5298c51e..342c5b24 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -23,6 +23,10 @@ This list is detailed and covers changes in each pre-release version.
 Unreleased
 ----------
 
+- Deprecated: The ``annotate`` command and the ``Coverage.annotate`` function
+  will be removed in a future version, unless people let me know that they are
+  using it.  Get in touch if you do: ned@nedbatchelder.com.
+
 - Feature: Coverage now sets an environment variable, ``COVERAGE_RUN`` when
   running your code with the ``coverage run`` command.  The value is not
   important, and may change in the future.  Closes `issue 553`_.
@@ -43,7 +47,7 @@ Unreleased
 
 - Feature: Added support for PyPy 3.8.
 
-- Fix: more generated code is now excluded from measurement.  Code such as
+- Fix: More generated code is now excluded from measurement.  Code such as
   `attrs`_ boilerplate, or doctest code, was being measured though the
   synthetic line numbers meant they were never reported.  Once Cython was
   involved though, the generated .so files were parsed as Python, raising
diff --git a/coverage/control.py b/coverage/control.py
index a96f558a..ae4b14b3 100644
--- a/coverage/control.py
+++ b/coverage/control.py
@@ -932,6 +932,11 @@ class Coverage:
     ):
         """Annotate a list of modules.
 
+        .. note::
+           This method has been obsoleted by more modern reporting tools,
+           including the :meth:`html_report` method.  It will be removed in a
+           future version.
+
         Each module in `morfs` is annotated.  The source is written to a new
         file, named with a ",cover" suffix, with each line prefixed with a
         marker to indicate the coverage of the line.  Covered lines have ">",
@@ -940,6 +945,9 @@ class Coverage:
         See :meth:`report` for other arguments.
 
         """
+        print("The annotate command will be removed in a future version.")
+        print("Get in touch if you still use it: ned@nedbatchelder.com")
+
         with override_config(self,
             ignore_errors=ignore_errors, report_omit=omit,
             report_include=include, report_contexts=contexts,
diff --git a/doc/cmd.rst b/doc/cmd.rst
index 2ce7cc13..b674e298 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -511,6 +511,11 @@ Other common reporting options are described above in :ref:`cmd_reporting`.
 Text annotation: ``coverage annotate``
 --------------------------------------
 
+.. note::
+   The **annotate** command has been obsoleted by more modern reporting tools,
+   including the **html** command.  **annotate** will be removed in a future
+   version.
+
 The **annotate** command produces a text annotation of your source code.  With
 a ``-d`` argument specifying an output directory, each Python file becomes a
 text file in that directory.  Without ``-d``, the files are written into the
diff --git a/tests/test_annotate.py b/tests/test_annotate.py
index 15b31273..97f2080b 100644
--- a/tests/test_annotate.py
+++ b/tests/test_annotate.py
@@ -123,5 +123,10 @@ class AnnotationGoldTest(CoverageTest):
         cov = coverage.Coverage()
         self.start_import_stop(cov, "mae")
         cov.annotate()
-        assert self.stdout() == "1\n2\n"
+        assert self.stdout() == (
+            "1\n" +
+            "2\n" +
+            "The annotate command will be removed in a future version.\n" +
+            "Get in touch if you still use it: ned@nedbatchelder.com\n"
+            )
         compare(gold_path("annotate/mae"), ".", "*,cover")