provide space for new 2.0 changes not part of upgrade path

As we are going to be adding new improvements such as
variant, cython, psycopg3, more RETURNING support,
fast execution helpers, and probably a lot more, the
2.0 migration doc needs to also still have the "what's new in 2.0?"
thing going on as well.   Organize the document so it has space
to introduce these sections, as well as the existing
1.4->2.0 migration sections.

If the "What's New" document gets large, we will break up this
page into two separate pages, it's already quite large, so
the proposal would be the exising migration doc becomes
a separate special migration document.

Change-Id: I62496b30229806f4a82d1f92b3f4eda53e64df57

diff --git a/doc/build/changelog/index.rst b/doc/build/changelog/index.rst
index 101585f15820843ade992a2c83ae3cc37b01c6eb..2efd618dc8935180b2850c3720835e2e40119a04 100644 (file)
--- a/doc/build/changelog/index.rst
+++ b/doc/build/changelog/index.rst
@@ -9,14 +9,6 @@ within the main documentation.
 Current Migration Guide
 -----------------------
 
-.. toctree::
-   :titlesonly:
-
-   migration_20
-
-SQLAlchemy 2.0 Overview and Status
-----------------------------------
-
 .. toctree::
    :titlesonly:
 
@@ -51,6 +43,7 @@ Older Migration Guides
 .. toctree::
    :titlesonly:
 
+   migration_14
    migration_13
    migration_12
    migration_11

diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst
index afca522df3ab22e32693b5be74d7e2878826ba0f..b75cefb31ee976f538d6caf1ded3495bc08a1a16 100644 (file)
--- a/doc/build/changelog/migration_20.rst
+++ b/doc/build/changelog/migration_20.rst
@@ -1,11 +1,14 @@
 .. _migration_20_toplevel:
 
 =============================
-Migrating to SQLAlchemy 2.0
+What's New in SQLAlchemy 2.0?
 =============================
 
 .. admonition:: About this document
 
+    This document describes changes between SQLAlchemy version 1.4
+    and SQLAlchemy version 2.0.
+
     SQLAlchemy 2.0 presents a major shift for a wide variety of key
     SQLAlchemy usage patterns in both the Core and ORM components.   The goal
     of this release is to make a slight readjustment in some of the most
@@ -28,9 +31,64 @@ Migrating to SQLAlchemy 2.0
     :class:`.orm.query.Query`  and Declarative. It also hopes standardize some
     newer capabilities that have proven to be very effective.
 
+The 1.4->2.0 Migration Path
+===========================
+
+The most prominent architectural features and API changes that are considered
+to be "SQLAlchemy 2.0" were in fact released as fully available within the 1.4
+series, to provide for a clean upgrade path from the 1.x to the 2.x series
+as well as to serve as a beta platform for the features themselves.  These
+changes include:
+
+* :ref:`New ORM statement paradigm <change_5159>`
+* :ref:`SQL caching throughout Core and ORM <change_4639>`
+* :ref:`New Declarative features, ORM integration <change_5508>`
+* :ref:`New Result object <change_result_14_core>`
+* :ref:`select() / case() Accept Positional Expressions <change_5284>`
+* :ref:`asyncio support for Core and ORM <change_3414>`
+
+The above bullets link to the description of these new paradigms as introduced
+in SQLAlchemy 1.4. in the :ref:`migration_14_toplevel` document.
+
+For SQLAlchemy 2.0, all API features and behaviors
+that were marked as :ref:`deprecated for 2.0 <deprecation_20_mode>` are
+now finalized; in particular, major APIs that are **no longer present**
+include:
+
+* :ref:`Bound MetaData and connectionless execution <migration_20_implicit_execution>`
+* :ref:`Emulated autocommit on Connection <migration_20_autocommit>`
+* :ref:`The Session.autocommit parameter / mode <migration_20_session_autocommit>`
+* :ref:`List / keyword arguments to select() <migration_20_5284>`
+* Python 2 support
+
+The above bullets refer to the most prominent fully backwards-incompatible
+changes that are finalized in the 2.0 release. The migration path for
+applications to accommodate for these changes as well as others is framed as
+a transition path first into the 1.4 series of SQLAlchemy where the "future"
+APIs are available to provide for the "2.0" way of working, and then to the
+2.0 series where the no-longer-used APIs above and others are removed.
+
+The complete steps for this migration path are later in this document at
+:ref:`migration_20_overview`.
+
+New Features and Improvements
+=============================
+
+This section covers new features and improvements in SQLAlchemy 2.0 which
+are not otherwise part of the major 1.4->2.0 migration path.
+
+Behavioral Changes
+==================
 
-Overview
-========
+This section covers behavioral changes made in SQLAlchemy 2.0 which are
+not otherwise part of the major 1.4->2.0 migration path; changes here are
+not expected to have significant effects on backwards compatibility.
+
+
+.. _migration_20_overview:
+
+1.x -> 2.x Migration Overview
+=============================
 
 The SQLAlchemy 2.0 transition presents itself in the SQLAlchemy 1.4 release as
 a series of steps that allow an application of any size or complexity to be
@@ -1966,6 +2024,7 @@ the :func:`_orm.selectinload` strategy presents a collection-oriented
 eager loader that is superior in most respects to :func:`_orm.joinedload`
 and should be preferred.
 
+.. _migration_20_session_autocommit:
 
 Autocommit mode removed from Session; autobegin support added
 -------------------------------------------------------------