- reduce verbiage in mutation.py regarding legacy style, place under versionadded

3 files changed, 11 insertions, 10 deletions

diff --git a/doc/build/changelog/changelog_07.rst b/doc/build/changelog/changelog_07.rst
index 40dcc832c..da89bbde3 100644
--- a/doc/build/changelog/changelog_07.rst
+++ b/doc/build/changelog/changelog_07.rst
@@ -4181,6 +4181,10 @@
 
       Mutation Event Extension, supercedes "mutable=True"
 
+      .. seealso::
+
+          :ref:`07_migration_mutation_extension`
+
     .. change::
         :tags: orm
         :tickets: 1980
diff --git a/doc/build/changelog/migration_07.rst b/doc/build/changelog/migration_07.rst
index 95d6cb7db..207397f52 100644
--- a/doc/build/changelog/migration_07.rst
+++ b/doc/build/changelog/migration_07.rst
@@ -278,15 +278,16 @@ unchanged:
 
 :ticket:`1923`
 
+.. _07_migration_mutation_extension:
+
 Mutation event extension, supersedes "mutable=True"
 ---------------------------------------------------
 
-A new extension, `Mutation Tracking <http://www.sqlalchemy.o
-rg/docs/07/orm/extensions/mutable.html>`_, provides a
+A new extension, :ref:`mutable_toplevel`, provides a
 mechanism by which user-defined datatypes can provide change
 events back to the owning parent or parents.   The extension
 includes an approach for scalar database values, such as
-those managed by ``PickleType``, ``postgresql.ARRAY``, or
+those managed by :class:`.PickleType`, ``postgresql.ARRAY``, or
 other custom ``MutableType`` classes, as well as an approach
 for ORM "composites", those configured using :func:`~.sqlalchemy.orm.composite`.
 
diff --git a/lib/sqlalchemy/ext/mutable.py b/lib/sqlalchemy/ext/mutable.py
index 37c599e1d..1933d44ab 100644
--- a/lib/sqlalchemy/ext/mutable.py
+++ b/lib/sqlalchemy/ext/mutable.py
@@ -7,13 +7,9 @@
 """Provide support for tracking of in-place changes to scalar values,
 which are propagated into ORM change events on owning parent objects.
 
-The :mod:`sqlalchemy.ext.mutable` extension replaces SQLAlchemy's legacy
-approach to in-place mutations of scalar values, established by the
-``types.MutableType`` class as well as the ``mutable=True`` type flag,
-with a system that allows change events to be propagated from the value to
-the owning parent, thereby removing the need for the ORM to maintain copies
-of values as well as the very expensive requirement of scanning through all
-"mutable" values on each flush call, looking for changes.
+.. versionadded:: 0.7 :mod:`sqlalchemy.ext.mutable` replaces SQLAlchemy's
+   legacy approach to in-place mutations of scalar values; see
+   :ref:`07_migration_mutation_extension`.
 
 .. _mutable_scalars: