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
diff --git a/‎lib/matplotlib/__init__.py
+2-2 b/‎lib/matplotlib/__init__.py
+2-2
@@ -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.
@@ -601,6 +601,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)
 
@@ -1463,7 +1463,7 @@ def _replacer(data, key):
 
 
 def _preprocess_data(replace_names=None, replace_all_args=False,
-                        label_namer=None, positional_parameter_names=None):
+                     label_namer=None, positional_parameter_names=None):
     """
     A decorator to add a 'data' kwarg to any a function.  The signature
     of the input function must include the ax argument at the first position ::
@@ -1720,7 +1720,7 @@ def inner(ax, *args, **kwargs):
             if len(replace_names) != 0:
                 _repl = "* All arguments with the following names: '{names}'."
             if replace_all_args:
-                _repl += "\n* All positional arguments."
+                _repl += "\n    * All positional arguments."
             _repl = _repl.format(names="', '".join(sorted(replace_names)))
         inner.__doc__ = (pre_doc +
                          _DATA_DOC_APPENDIX.format(replaced=_repl))