From 50dd11c838d97347e93880d0810a741d9acffde7 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Wed, 2 Aug 2023 10:25:20 +0200
Subject: [PATCH] DOC: Add a warning that ticks are not persistent

---
 lib/matplotlib/axis.py              | 53 +++++++++++++++++++++++++++--
 lib/matplotlib/projections/polar.py | 22 ++++++++++++
 2 files changed, 73 insertions(+), 2 deletions(-)

diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
index aeee67e3816d..449d8b402249 100644
--- a/lib/matplotlib/axis.py
+++ b/lib/matplotlib/axis.py
@@ -619,6 +619,18 @@ class Axis(martist.Artist):
         The acceptance radius for containment tests. See also `.Axis.contains`.
     majorTicks : list of `.Tick`
         The major ticks.
+
+        .. warning::
+
+            Ticks are not guaranteed to be persistent. Various operations
+            can create, delete and modify the Tick instances. There is an
+            imminent risk that changes to individual ticks will not
+            survive if you work on the figure further (including also
+            panning/zooming on a displayed figure).
+
+            Working on the individual ticks is a method of last resort.
+            Use `.set_tick_params` instead if possible.
+
     minorTicks : list of `.Tick`
         The minor ticks.
     """
@@ -1591,7 +1603,20 @@ def get_minor_formatter(self):
         return self.minor.formatter
 
     def get_major_ticks(self, numticks=None):
-        r"""Return the list of major `.Tick`\s."""
+        r"""
+        Return the list of major `.Tick`\s.
+
+        .. warning::
+
+            Ticks are not guaranteed to be persistent. Various operations
+            can create, delete and modify the Tick instances. There is an
+            imminent risk that changes to individual ticks will not
+            survive if you work on the figure further (including also
+            panning/zooming on a displayed figure).
+
+            Working on the individual ticks is a method of last resort.
+            Use `.set_tick_params` instead if possible.
+        """
         if numticks is None:
             numticks = len(self.get_majorticklocs())
 
@@ -1604,7 +1629,20 @@ def get_major_ticks(self, numticks=None):
         return self.majorTicks[:numticks]
 
     def get_minor_ticks(self, numticks=None):
-        r"""Return the list of minor `.Tick`\s."""
+        r"""
+        Return the list of minor `.Tick`\s.
+
+        .. warning::
+
+            Ticks are not guaranteed to be persistent. Various operations
+            can create, delete and modify the Tick instances. There is an
+            imminent risk that changes to individual ticks will not
+            survive if you work on the figure further (including also
+            panning/zooming on a displayed figure).
+
+            Working on the individual ticks is a method of last resort.
+            Use `.set_tick_params` instead if possible.
+        """
         if numticks is None:
             numticks = len(self.get_minorticklocs())
 
@@ -1952,6 +1990,17 @@ def set_ticklabels(self, labels, *, minor=False, fontdict=None, **kwargs):
         **kwargs
             Text properties.
 
+            .. warning::
+
+                This only sets the properties of the current ticks.
+                Ticks are not guaranteed to be persistent. Various operations
+                can create, delete and modify the Tick instances. There is an
+                imminent risk that these settings can get lost if you work on
+                the figure further (including also panning/zooming on a
+                displayed figure).
+
+                Use `.set_tick_params` instead if possible.
+
         Returns
         -------
         list of `.Text`\s
diff --git a/lib/matplotlib/projections/polar.py b/lib/matplotlib/projections/polar.py
index 33c54205f742..e4a99a01a774 100644
--- a/lib/matplotlib/projections/polar.py
+++ b/lib/matplotlib/projections/polar.py
@@ -1317,6 +1317,17 @@ def set_thetagrids(self, angles, labels=None, fmt=None, **kwargs):
         **kwargs
             *kwargs* are optional `.Text` properties for the labels.
 
+            .. warning::
+
+                This only sets the properties of the current ticks.
+                Ticks are not guaranteed to be persistent. Various operations
+                can create, delete and modify the Tick instances. There is an
+                imminent risk that these settings can get lost if you work on
+                the figure further (including also panning/zooming on a
+                displayed figure).
+
+                Use `.set_tick_params` instead if possible.
+
         See Also
         --------
         .PolarAxes.set_rgrids
@@ -1369,6 +1380,17 @@ def set_rgrids(self, radii, labels=None, angle=None, fmt=None, **kwargs):
         **kwargs
             *kwargs* are optional `.Text` properties for the labels.
 
+            .. warning::
+
+                This only sets the properties of the current ticks.
+                Ticks are not guaranteed to be persistent. Various operations
+                can create, delete and modify the Tick instances. There is an
+                imminent risk that these settings can get lost if you work on
+                the figure further (including also panning/zooming on a
+                displayed figure).
+
+                Use `.set_tick_params` instead if possible.
+
         See Also
         --------
         .PolarAxes.set_thetagrids