DOC: document that appearance is part of our stable API

tacaswell · tacaswell · commit bc4be15a4ecf · 2022-08-11T23:30:33.000-04:00
This is a long standing policy (the reference I found is from 2015 and I
remember that being the position when I started to work on Matplotlib in 2012)
and is being documented here.

This position is consistent with our testing scheme (that strives for pixel
identical renderings across platforms, Python versions, and Matplotlib
versions).

Changing the default colormap (and the rest of the styling) was the proximal
cause of 2.0 not being 1.6 due to this policy.
diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst
@@ -289,6 +289,12 @@ API consistency and stability are of great value. Therefore, API changes
 (e.g. signature changes, behavior changes, removals) will only be conducted
 if the added benefit is worth the user effort for adapting.
 
+Because we are a visualization library our primary output is the final
+visualization the user sees.  Thus it is our :ref:`long standing
+<color_changes>`_ policy that the appearance of the figure is part of the API
+and any changes, either semantic or esthetic, will be treated as a
+backwards-incompatible API change.
+
 API changes in Matplotlib have to be performed following the deprecation process
 below, except in very rare circumstances as deemed necessary by the development team.
 This ensures that users are notified before the change will take effect and thus
