From 526b85635cd47617b8f6f8edd9e8033c5e42570e Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Sun, 7 Oct 2018 18:51:53 +0200
Subject: [PATCH] Deprecate Axes3D.plot_surface(shade=None)

---
 doc/api/next_api_changes/2018-10-07-TH-deprecations.rst | 9 +++++++++
 lib/mpl_toolkits/mplot3d/axes3d.py                      | 6 ++++++
 2 files changed, 15 insertions(+)
 create mode 100644 doc/api/next_api_changes/2018-10-07-TH-deprecations.rst

diff --git a/doc/api/next_api_changes/2018-10-07-TH-deprecations.rst b/doc/api/next_api_changes/2018-10-07-TH-deprecations.rst
new file mode 100644
index 000000000000..cf128bf72ed6
--- /dev/null
+++ b/doc/api/next_api_changes/2018-10-07-TH-deprecations.rst
@@ -0,0 +1,9 @@
+Deprecations
+````````````
+
+The following keyword arguments are deprecated:
+
+- Passing ``shade=None`` to
+  `~mpl_toolkits.mplot3d.axes3d.Axes3D.plot_surface` is deprecated. This was
+  an unintended implementation detail with the same semantics as
+  ``shade=False``. Please use the latter code instead.
\ No newline at end of file
diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py
index f16c9717337d..5cdc42b6a1fe 100644
--- a/lib/mpl_toolkits/mplot3d/axes3d.py
+++ b/lib/mpl_toolkits/mplot3d/axes3d.py
@@ -1651,6 +1651,12 @@ def plot_surface(self, X, Y, Z, *args, norm=None, vmin=None,
 
         cmap = kwargs.get('cmap', None)
         shade = kwargs.pop('shade', cmap is None)
+        if shade is None:
+            cbook.warn_deprecated(
+                "3.1",
+                "Passing shade=None to Axes3D.plot_surface() is deprecated "
+                "since matplotlib 3.1 and will change its semantic or raise "
+                "an error in matplotlib 3.3. Please use shade=False instead.")
 
         # evenly spaced, and including both endpoints
         row_inds = list(range(0, rows-1, rstride)) + [rows-1]