update docs for "copy column" warning

these docs failed to mention we're talking about ORM flush

References: #12650
Change-Id: I3a1655ba99e98021327c90d5cd0c0f8258f4ddc6

diff --git a/doc/build/orm/join_conditions.rst b/doc/build/orm/join_conditions.rst
index ef0575d66190822099ee229fa7ffb3187ac4f4b9..3c69150413597b345db9e8d0eaa3db9688d99075 100644 (file)
--- a/doc/build/orm/join_conditions.rst
+++ b/doc/build/orm/join_conditions.rst
@@ -422,13 +422,19 @@ What this refers to originates from the fact that ``Article.magazine_id`` is
 the subject of two different foreign key constraints; it refers to
 ``Magazine.id`` directly as a source column, but also refers to
 ``Writer.magazine_id`` as a source column in the context of the
-composite key to ``Writer``.   If we associate an ``Article`` with a
-particular ``Magazine``, but then associate the ``Article`` with a
-``Writer`` that's  associated  with a *different* ``Magazine``, the ORM
-will overwrite ``Article.magazine_id`` non-deterministically, silently
-changing which magazine to which we refer; it may
-also attempt to place NULL into this column if we de-associate a
-``Writer`` from an ``Article``.  The warning lets us know this is the case.
+composite key to ``Writer``.
+
+When objects are added to an ORM :class:`.Session` using :meth:`.Session.add`,
+the ORM :term:`flush` process takes on the task of reconciling object
+refereneces that correspond to :func:`_orm.relationship` configurations and
+delivering this state to the databse using INSERT/UPDATE/DELETE statements.  In
+this specific example, if we associate an ``Article`` with a particular
+``Magazine``, but then associate the ``Article`` with a ``Writer`` that's
+associated  with a *different* ``Magazine``, this flush process will overwrite
+``Article.magazine_id`` non-deterministically, silently changing which magazine
+to which we refer; it may also attempt to place NULL into this column if we
+de-associate a ``Writer`` from an ``Article``.  The warning lets us know that
+this scenario may occur during ORM flush sequences.
 
 To solve this, we need to break out the behavior of ``Article`` to include
 all three of the following features: