Deprecate Mapper.order_by

This is an old parameter no longer relevant to how SQLAlchemy
works, once the Query object was introduced.  By deprecating it
we establish that we aren't supporting non-working use cases
and that we encourage applications to move off of the use of this
parameter.

Fixes: #3394
Change-Id: I25b9a38142a1537bbcb27d3e8b66a8b265140072

1 files changed, 18 insertions, 0 deletions

diff --git a/doc/build/changelog/migration_11.rst b/doc/build/changelog/migration_11.rst
index 2991d1414..7dd071782 100644
--- a/doc/build/changelog/migration_11.rst
+++ b/doc/build/changelog/migration_11.rst
@@ -900,6 +900,24 @@ when a non-eagerly-loaded attribute is accessed for read::
 
 :ticket:`3512`
 
+.. _change_3394:
+
+Mapper.order_by is deprecated
+-----------------------------
+
+This old parameter from the very first versions of SQLAlchemy was part of
+the original design of the ORM which featured the :class:`.Mapper` object
+as a public-facing query structure.   This role has long since been replaced
+by the :class:`.Query` object, where we use :meth:`.Query.order_by` to
+indicate the ordering of results in a way that works consistently for any
+combination of SELECT statements, entities and SQL expressions.   There are
+many areas in which :paramref:`.Mapper.order_by` doesn't work as expected
+(or what would be expected is not clear), such as when queries are combined
+into unions; these cases are not supported.
+
+
+:ticket:`3394`
+
 New Features and Improvements - Core
 ====================================