DOC: add whats_new and api_changes entries for gc hatch methods

tacaswell · tacaswell · commit a58b0d1ed8ce · 2017-01-29T14:31:52.000-05:00
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -10,6 +10,30 @@ out what caused the breakage and how to fix it by updating your code.
 For new features that were added to Matplotlib, please see
 :ref:`whats-new`.
 
+API Changes in 2.0.1
+====================
+
+Extensions to `matplotlib.backend_bases.GraphicsContextBase`
+------------------------------------------------------------
+
+To better support controlling the color of hatches, the method
+`matplotlib.backend_bases.GraphicsContextBase.set_hatch_color` was
+added to the expected API of ``GraphicsContext`` classes.  Calls to
+this method are currently wrapped with a ``try:...except Attribute:``
+block to preserve back-compatibility with any third-party backends
+which do not extend `~matplotlib.backend_bases.GraphicsContextBase`.
+
+This value can be accessed in the backends via
+`matplotlib.backend_bases.GraphicsContextBase.get_hatch_color` (which
+was added in 2.0 see :ref:`gc_get_hatch_color_wn`) and should be used
+to color the hatches.
+
+In the future there may also be ``hatch_linewidth`` and
+``hatch_density`` related methods added.  It is encouraged, but not
+required that third-party backends extend
+`~matplotlib.backend_bases.GraphicsContextBase` to make adapting to
+these changes easier.
+
 
 API Changes in 2.0.0
 ====================
diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst
@@ -313,6 +313,20 @@ value of ``None`` instead of ``2``. If ``None`` is given as ``zorder``,
 :func:`streamplot` has a default ``zorder`` of
 ``matplotlib.lines.Line2D.zorder``.
 
+.. _gc_get_hatch_color_wn:
+
+Extension to `matplotlib.backend_bases.GraphicsContextBase`
+-----------------------------------------------------------
+
+To support standardizing hatch behavior across the backends we ship
+the `matplotlib.backend_bases.GraphicsContextBase.get_hatch_color`
+method as added to `matplotlib.backend_bases.GraphicsContextBase`.
+This is only used during the render process in the backends we ship so
+will not break any third-party backends.
+
+If you maintain a third-party backend which extends
+`~matplotlib.backend_bases.GraphicsContextBase` this method is now
+available to you and should be used to color hatch patterns.
 
 Previous Whats New
 ==================
