matplotlib
diff --git a/‎doc/api/api_changes/2017-08-27-TAC.rst
+22 b/‎doc/api/api_changes/2017-08-27-TAC.rst
+22
diff --git a/‎doc/users/dflt_style_changes.rst
+2 b/‎doc/users/dflt_style_changes.rst
+2
diff --git a/‎examples/pie_and_polar_charts/nested_pie.py
+3-3 b/‎examples/pie_and_polar_charts/nested_pie.py
+3-3
@@ -0,0 +1,22 @@
+Change to signatures of :meth:`~matplotlib.axes.Axes.bar` & :meth:`~matplotlib.axes.Axes.barh`
+----------------------------------------------------------------------------------------------
+
+For 2.0 the :ref:`default value of *align* <barbarh_align>` changed to
+``'center'``.  However this caused the signature of
+:meth:`~matplotlib.axes.Axes.bar` and
+:meth:`~matplotlib.axes.Axes.barh` to be misleading as the first parameters were
+still *left* and *bottom* respectively::
+
+  bar(left, height, *, align='center', **kwargs)
+  barh(bottom, width, *, align='center', **kwargs)
+
+despite behaving as the center in both cases. The methods now take ``*args, **kwargs``
+is input and are documented to have the primary signatures of::
+
+  bar(x, height, *, align='center', **kwargs)
+  barh(y, width, *, align='center', **kwargs)
+
+Passing *left* and *bottom* as keyword arguments to
+:meth:`~matplotlib.axes.Axes.bar` and
+:meth:`~matplotlib.axes.Axes.barh` respectively will warn.
+Support will be removed in Matplotlib 3.0.
@@ -599,6 +599,8 @@ The default value of the ``linecolor`` kwarg for `~matplotlib.Axes.hexbin` has
 changed from ``'none'`` to ``'face'``. If 'none' is now supplied, no line edges
 are drawn around the hexagons.
 
+.. _barbarh_align:
+
 ``bar`` and ``barh``
 --------------------
 
 
@@ -44,17 +44,17 @@
 left_middle = np.arange(0.0, 2 * np.pi, 2 * np.pi / 12)
 left_outer = np.arange(0.0, 2 * np.pi, 2 * np.pi / 9)
 
-ax.bar(left=left_inner,
+ax.bar(x=left_inner,
        width=2 * np.pi / 6, bottom=0, color='C0',
        linewidth=2, edgecolor='w',
        height=np.zeros_like(left_inner) + 5)
 
-ax.bar(left=left_middle,
+ax.bar(x=left_middle,
        width=2 * np.pi / 12, bottom=5, color='C1',
        linewidth=2, edgecolor='w',
        height=np.zeros_like(left_middle) + 2)
 
-ax.bar(left=left_outer,
+ax.bar(x=left_outer,
        width=2 * np.pi / 9, bottom=7, color='C2',
        linewidth=2, edgecolor='w',
        height=np.zeros_like(left_outer) + 3)