- add migration note for #3084

2 files changed, 19 insertions, 0 deletions

diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst
index 86bf7df64..859adae81 100644
--- a/doc/build/changelog/changelog_10.rst
+++ b/doc/build/changelog/changelog_10.rst
@@ -142,6 +142,10 @@
         the incoming data in an ordered fashion.  Pull request
         courtesy Sebastian Bank.
 
+        .. seealso::
+
+            :ref:`feature_3084`
+
     .. change::
         :tags: feature, orm
         :pullreq: github:164
diff --git a/doc/build/changelog/migration_10.rst b/doc/build/changelog/migration_10.rst
index a7a668fbe..8238334c2 100644
--- a/doc/build/changelog/migration_10.rst
+++ b/doc/build/changelog/migration_10.rst
@@ -2041,6 +2041,21 @@ columns regardless of how the object was constructed or its current
 state.
 
 
+.. _feature_3084:
+
+MetaData sorting of Tables is now fully deterministic
+-----------------------------------------------------
+
+The sorting of tables which results when emitting :meth:`.MetaData.create_all`,
+:meth:`.MetaData.drop_all`, and :meth:`.MetaData.sorted_tables` is now
+fully deterministic; that is, the :class:`.Table` objects are as always
+sorted by dependency, but the full ordering is generated in a deterministic
+way based on the set of tables first sorted alphabetically by name,
+then run through the foreign key sort, such that these methods will
+produce the identical topological ordering each time.
+
+:ticket:`3084`
+
 .. _bug_3170:
 
 null(), false() and true() constants are no longer singletons