DOC: add API change

jklymak · jklymak · commit 02034885750a · 2021-02-20T10:07:46.000-08:00
diff --git a/doc/api/next_api_changes/behavior/18900-JMK.rst b/doc/api/next_api_changes/behavior/18900-JMK.rst
@@ -0,0 +1,31 @@
+Axes used to make colorbar now wrapped
+======================================
+
+The axes used to place a colorbar is now wrapped by a new parent class
+(``ColorbarAxes``). This affects calls like::
+
+    cb = fig.colorbar(im, cax=cax)
+    cax.tick_params()
+
+so that this will no longer affect the visible axes ticks.  Rather call
+methods on the axes stored on the colorbar object::
+
+    cb = fig.colorbar(im, cax=cax)
+    cb.ax.tick_params()
+
+If necessary, the original axes can be accessed via::
+
+    assert cb.ax.parent_axes == cax
+
+This change means that the parent axes (``cb.ax.parent_axes``) handles the
+placement of the colorbar axes object, and its aspect ratio, but the child
+axes (``cb.ax``)   handles all the tick parameters, labelling, and holds the
+artists that make up the colorbar.
+
+Colorbar lines no longer clipped
+================================
+
+If a colorbar has lines added to it (e.g. for contour lines), these will
+no longer be clipped.  This is an improvement for lines on the edge of
+the colorbar, but could lead to lines off the colorbar if the limits of
+the colorbar are changed.
