4 files changed, 67 insertions, 0 deletions
diff --git a/docs/howto/initial-data.txt b/docs/howto/initial-data.txt
index cf3f65d299..dd6a099b9d 100644
--- a/docs/howto/initial-data.txt
+++ b/docs/howto/initial-data.txt
@@ -121,6 +121,17 @@ the order in which they're executed. The only thing you can assume is
 that, by the time your custom data files are executed, all the
 database tables already will have been created.
 
+.. admonition:: Initial SQL data and testing
+
+    This technique *cannot* be used to provide initial data for
+    testing purposes. Django's test framework flushes the contents of
+    the test database after each test; as a result, any data added
+    using the custom SQL hook will be lost.
+
+    If you require data for a test case, you should add it using
+    either a :ref:`test fixture <topics-testing-fixtures>`, or
+    programatically add it during the ``setUp()`` of your test case.
+
 Database-backend-specific SQL data
 ----------------------------------
 
diff --git a/docs/releases/1.2.5.txt b/docs/releases/1.2.5.txt
new file mode 100644
index 0000000000..d8efb9d607
--- /dev/null
+++ b/docs/releases/1.2.5.txt
@@ -0,0 +1,46 @@
+==========================
+Django 1.2.5 release notes
+==========================
+
+Welcome to Django 1.2.5!
+
+This is the fifth "bugfix" release in the Django 1.2 series,
+improving the stability and performance of the Django 1.2 codebase.
+
+With one exception, Django 1.2.5 maintains backwards compatibility
+with Django 1.2.4, but contain a number of fixes and other
+improvements. Django 1.2.5 is a recommended upgrade for any
+development or deployment currently using or targeting Django 1.2.
+
+For full details on the new features, backwards incompatibilities, and
+deprecated features in the 1.2 branch, see the :doc:`/releases/1.2`.
+
+One backwards incompatibility
+=============================
+
+Django provides a custom SQL hooks as a way to inject hand-crafted SQL
+into the database synchronization process. One of the possible uses
+for this custom SQL is to insert data into your database. If your
+custom SQL contains ``INSERT`` statements, those insertions will be
+performed every time your database is synchronized. This includes the
+synchronization of any test databases that are created when you run a
+test suite.
+
+However, in the process of testing the Django 1.3, it was discovered
+that this feature has never completely worked as advertised. When
+using database backends that don't support transactions, or when using
+a TransactionTestCase, data that has been inserted using custom SQL
+will not be visible during the testing process.
+
+Unfortunately, there was no way to rectify this problem without
+introducing a backwards incompatibility. Rather than leave
+SQL-inserted initial data in an uncertain state, Django now enforces
+the policy that data inserted by custom SQL will *not* be visible
+during testing.
+
+This change only affects the testing process. You can still use custom
+SQL to load data into your production database as part of the syncdb
+process. If you require data to exist during test conditions, you
+should either insert it using :ref:`test fixtures
+<topics-testing-fixtures>`, or using the ``setUp()`` method of your
+test case.
diff --git a/docs/releases/index.txt b/docs/releases/index.txt
index 7abaf78565..133989b2c7 100644
--- a/docs/releases/index.txt
+++ b/docs/releases/index.txt
@@ -19,6 +19,7 @@ Final releases
 .. toctree::
    :maxdepth: 1
 
+   1.2.5
    1.2.4
    1.2.2
    1.2
diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
index df6baa2751..6ee6b116c8 100644
--- a/docs/topics/testing.txt
+++ b/docs/topics/testing.txt
@@ -1151,6 +1151,15 @@ documentation<dumpdata>` for more details.
     Fixtures with other names can always be installed manually using
     the :djadmin:`manage.py loaddata<loaddata>` command.
 
+.. admonition:: Initial SQL data and testing
+
+    Django provides a second way to insert initial data into models --
+    the :ref:`custom SQL hook <initial-sql>`. However, this technique
+    *cannot* be used to provide initial data for testing purposes.
+    Django's test framework flushes the contents of the test database
+    after each test; as a result, any data added using the custom SQL
+    hook will be lost.
+
 Once you've created a fixture and placed it in a ``fixtures`` directory in one
 of your :setting:`INSTALLED_APPS`, you can use it in your unit tests by
 specifying a ``fixtures`` class attribute on your :class:`django.test.TestCase`