DOC: add deprecation note

jklymak · jklymak · commit d6318a19dc95 · 2022-02-04T09:24:57.000+01:00
diff --git a/doc/api/next_api_changes/deprecations/22382-JK.rst b/doc/api/next_api_changes/deprecations/22382-JK.rst
@@ -0,0 +1,8 @@
+``arrow`` method is deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `~.axes.Axes.arrow` method is deprecated, and is scheduled to be
+removed in Matplotlib 3.9.  It only produces properly shaped
+arrow heads if the aspect ratio of the axes is 1, and the parameters to
+control the size of the arrow heads is in data space, and hence
+unintuitive.  Users should use `~.axes.Axes.annotate` to create arrows.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -4892,7 +4892,7 @@ def on_changed(collection):
 
         return collection
 
-    @_api.deprecated("3.6", alternative='annotate')
+    @_api.deprecated("3.6", alternative='annotate', removal='3.9')
     @docstring.dedent_interpd
     def arrow(self, x, y, dx, dy, **kwargs):
         """
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -114,6 +114,7 @@ def _safe_pyplot_import():
     return plt
 
 
+
 def register_backend(format, backend, description=None):
     """
     Register a backend for saving to a given file format.
