Warn about incompleteness of CocoaAgg backend

doc/api/api_changes.rst

@@ -12,6 +12,8 @@ For new features that were added to matplotlib, please see
 :ref:`whats-new`.
 
 
+.. _changes_in_1_3:
+
 Changes in 1.3.x
 ================
 
@@ -61,6 +63,9 @@ Changes in 1.3.x
     - `widgets.HorizontalSpanSelector` has been removed.  Use
       `widgets.SpanSelector` instead.
 
+* The CocoaAgg backend has been deprecated, with the possibility for
+  deletion or resurrection in a future release.
+
 * The top-level functions in `matplotlib.path` that are implemented in
   C++ were never meant to be public.  Instead, users should use the
   Pythonic wrappers for them in the `path.Path` and

lib/matplotlib/backends/backend_cocoaagg.py

@@ -25,6 +25,12 @@
 from AppKit import *
 from PyObjCTools import NibClassBuilder, AppHelper
 
+from matplotlib import cbook
+cbook.warn_deprecated(
+    '1.3',
+    message="The CocoaAgg backend is not a fully-functioning backend. "
+            "It may be removed in matplotlib 1.4.")
+
 import matplotlib
 from matplotlib.figure import Figure
 from matplotlib.backend_bases import FigureManagerBase, FigureCanvasBase
@@ -292,4 +298,3 @@ def WMEnable(name='Python'):
         print('SetFrontProcess', (err, psn), file=sys.stderr)
         return False
     return True
-