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

Author: nedbat

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: [email protected].
+
 - 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

coverage/control.py

@@ -932,6 +932,11 @@ def annotate(
     ):
         """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 @@ def annotate(
         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: [email protected]")
+
         with override_config(self,
             ignore_errors=ignore_errors, report_omit=omit,
             report_include=include, report_contexts=contexts,

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

tests/test_annotate.py

@@ -123,5 +123,10 @@ def f(x):
         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: [email protected]\n"
+            )
         compare(gold_path("annotate/mae"), ".", "*,cover")