- add a note to baked documentation indicating it is not

really of general use.  This extension is there only
for those who really want it based on observed performance
characteristics.

Change-Id: I2f612f26fdef4ddbeb1158ab1b344fad7083b11c
(cherry picked from commit cbe99b06679e2d2da1312f7d69b41f63bda1b41f)

diff --git a/doc/build/orm/extensions/baked.rst b/doc/build/orm/extensions/baked.rst
index 83cee51dace5bae29b4b4234d071ed725d0b0612..66745b9a1cccd86793464651111669cb32a7ad97 100644 (file)
--- a/doc/build/orm/extensions/baked.rst
+++ b/doc/build/orm/extensions/baked.rst
@@ -25,9 +25,12 @@ the caching of the SQL calls and result sets themselves is available in
 
 .. note::
 
-    The :mod:`sqlalchemy.ext.baked` extension should be considered
-    **experimental** as of 1.0.0.  It provides a dramatically different system
-    of producing queries which has yet to be proven at scale.
+    The :mod:`sqlalchemy.ext.baked` extension is **not for beginners**.  Using
+    it correctly requires a good high level understanding of how SQLAlchemy, the
+    database driver, and the backend database interact with each other.  This
+    extension presents a very specific kind of optimization that is not ordinarily
+    needed.  As noted above, it **does not cache queries**, only the string
+    formulation of the SQL itself.
 
 Synopsis
 --------