From d2a256a3ad48341e013b6e7a3e911495e5b5d31a Mon Sep 17 00:00:00 2001
From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sat, 9 Mar 2013 12:49:35 -0500
Subject: [PATCH] changelog

---
 doc/build/changelog/changelog_08.rst | 20 +++++++++-
 doc/build/changelog/migration_08.rst | 56 +++++++++++++++++++++++++++-
 2 files changed, 73 insertions(+), 3 deletions(-)

diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst
index c71f3be0cb..8c34dab09f 100644
--- a/doc/build/changelog/changelog_08.rst
+++ b/doc/build/changelog/changelog_08.rst
@@ -8,14 +8,30 @@
 
     .. note::
 
-      Be sure to *re-read* :doc:`migration_08` for this release.
       There are some new behavioral changes as of 0.8.0
-      not present in 0.8.0b2, including:
+      not present in 0.8.0b2.  They are present in the
+      migration document as follows:
 
       * :ref:`legacy_is_orphan_addition`
 
       * :ref:`metadata_create_drop_tables`
 
+      * :ref:`correlation_context_specific`
+
+    .. change::
+        :tags: bug, sql
+        :tickets: 2668
+
+      The behavior of SELECT correlation has been improved such that
+      the :meth:`.Select.correlate` and :meth:`.Select.correlate_except`
+      methods, as well as their ORM analogues, will still retain
+      "auto-correlation" behavior in that the FROM clause is modified
+      only if the output would be legal SQL; that is, the FROM clause
+      is left intact if the correlated SELECT is not used in the context
+      of an enclosing SELECT inside of the WHERE, columns, or HAVING clause.
+      The two methods now only specify conditions to the default
+      "auto correlation", rather than absolute FROM lists.
+
     .. change::
         :tags: feature, mysql
         :pullreq: 42
diff --git a/doc/build/changelog/migration_08.rst b/doc/build/changelog/migration_08.rst
index bb6d85e58f..971dd2f518 100644
--- a/doc/build/changelog/migration_08.rst
+++ b/doc/build/changelog/migration_08.rst
@@ -7,9 +7,10 @@ What's New in SQLAlchemy 0.8?
     This document describes changes between SQLAlchemy version 0.7,
     undergoing maintenance releases as of October, 2012,
     and SQLAlchemy version 0.8, which is expected for release
-    in late 2012.
+    in early 2013.
 
     Document date: October 25, 2012
+    Updated: March 9, 2013
 
 Introduction
 ============
@@ -1145,6 +1146,59 @@ entity, ``query.correlate(someentity)``.
 
 :ticket:`2179`
 
+.. _correlation_context_specific:
+
+Correlation is now always context-specific
+------------------------------------------
+
+To allow a wider variety of correlation scenarios, the behavior of
+:meth:`.Select.correlate` and :meth:`.Query.correlate` has changed slightly
+such that the SELECT statement will omit the "correlated" target from the
+FROM clause only if the statement is actually used in that context.  Additionally,
+it's no longer possible for a SELECT statement that's placed as a FROM
+in an enclosing SELECT statement to "correlate" (i.e. omit) a FROM clause.
+
+This change only makes things better as far as rendering SQL, in that it's no
+longer possible to render illegal SQL where there are insufficient FROM
+objects relative to what's being selected::
+
+    from sqlalchemy.sql import table, column, select
+
+    t1 = table('t1', column('x'))
+    t2 = table('t2', column('y'))
+    s = select([t1, t2]).correlate(t1)
+
+    print(s)
+
+Prior to this change, the above would return::
+
+    SELECT t1.x, t2.y FROM t2
+
+which is invalid SQL as "t1" is not referred to in any FROM clause.
+
+Now, in the absense of an enclosing SELECT, it returns::
+
+    SELECT t1.x, t2.y FROM t1, t2
+
+Within a SELECT, the correlation takes effect as expected::
+
+    s2 = select([t1, t2]).where(t1.c.x == t2.c.y).where(t1.c.x == s)
+
+    print (s2)
+
+    SELECT t1.x, t2.y FROM t1, t2
+    WHERE t1.x = t2.y AND t1.x =
+        (SELECT t1.x, t2.y FROM t2)
+
+This change is not expected to impact any existing applications, as
+the correlation behavior remains identical for properly constructed
+expressions.  Only an application that relies, most likely within a
+testing scenario, on the invalid string output of a correlated
+SELECT used in a non-correlating context would see any change.
+
+:ticket:`2668`
+
+
 .. _metadata_create_drop_tables:
 
 create_all() and drop_all() will now honor an empty list as such
-- 
2.47.2