From ad926a8eba43231dcc7277b44fe0c5e899e8ec0a Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 11 Aug 2022 23:30:19 -0400 Subject: [PATCH 1/2] DOC: add a missing link (7 years late) --- doc/devel/color_changes.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/devel/color_changes.rst b/doc/devel/color_changes.rst index 24aa15f29abf..f7646ded7c14 100644 --- a/doc/devel/color_changes.rst +++ b/doc/devel/color_changes.rst @@ -4,7 +4,8 @@ Default color changes ********************* -As discussed at length elsewhere [insert links], ``jet`` is an +As discussed at length `elsewhere `__ , +``jet`` is an empirically bad colormap and should not be the default colormap. Due to the position that changing the appearance of the plot breaks backward compatibility, this change has been put off for far longer From 3a51e7eda3a0f8cf4c707a563d4e26acf0d5f01a Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 11 Aug 2022 23:30:33 -0400 Subject: [PATCH 2/2] DOC: document that appearance is part of our stable API 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. --- doc/devel/contributing.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/devel/contributing.rst b/doc/devel/contributing.rst index 5023a7ecb640..28faf61f0771 100644 --- 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 +` 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