From 53211a69828bd7e6b351b430ef11fd0627424997 Mon Sep 17 00:00:00 2001
From: Thomas A Caswell <tcaswell@gmail.com>
Date: Wed, 2 Aug 2023 16:21:09 -0400
Subject: [PATCH] Backport PR #26436: 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 4c20751b955c..ecaa7ddf7964 100644
--- a/lib/matplotlib/axis.py
+++ b/lib/matplotlib/axis.py
@@ -628,6 +628,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.
     """
@@ -1593,7 +1605,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())
 
@@ -1606,7 +1631,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())
 
@@ -1949,6 +1987,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 3243c76d8661..b7e5c83aff7a 100644
--- a/lib/matplotlib/projections/polar.py
+++ b/lib/matplotlib/projections/polar.py
@@ -1318,6 +1318,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
@@ -1370,6 +1381,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