note that 2.0 has behavioral changes outside of the 1.4->2.0 process

Change-Id: I0ab9611c75f592acec73ca92271f970eae74d7ab
(cherry picked from commit 2c1550af60e5fc8303990519b3ae497401196348)

diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst
index f7009a28d579b8fef668a6c3ef42c5f5c154c5e6..15e6edfa3b29c1ac3b99355cb5e2458d3aed6adb 100644 (file)
--- a/doc/build/changelog/migration_20.rst
+++ b/doc/build/changelog/migration_20.rst
@@ -48,9 +48,12 @@ new ORM declarative system that unifies classical and declarative mapping,
 support for Python dataclasses, and asyncio support for Core and ORM.
 
 The steps to achieve 2.0 migration are in the following subsections; overall,
-the general strategy is that once an application runs on 1.4 with all
-warning flags turned on and does not emit any 2.0-deprecation warnings, it is
-now cross-compatible with SQLAlchemy 2.0.
+the general strategy is that once an application runs on 1.4 with all warning
+flags turned on and does not emit any 2.0-deprecation warnings, it is now
+**mostly** cross-compatible with SQLAlchemy 2.0. **Please note there may be
+additional API and behavioral changes that may behave differently when running
+against SQLAlchemy 2.0; always test code against an actual SQLAlchemy 2.0
+release as the final step in migrating**.
 
 
 First Prerequisite, step one - A Working 1.3 Application
@@ -468,6 +471,18 @@ that descend from ``Base``::
    that don't use :class:`_orm.Mapped` to remain usable.
 
 
+.. _migration_20_step_seven:
+
+Migration to 2.0 Step Seven - Test against a SQLAlchemy 2.0 Release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As mentioned previously, SQLAlchemy 2.0 has additional API and behavioral
+changes that are intended to be backwards compatible, however may introduce
+some incompatibilities nonetheless.  Therefore after the overall porting
+process is complete, the final step is to test against the most recent release
+of SQLAlchemy 2.0 to correct for any remaining issues that might be present.
+
+
 2.0 Migration - Core Connection / Transaction
 =============================================