From c9b22707b0703db6c6ddaebdd00e2cd33d182e40 Mon Sep 17 00:00:00 2001
From: Jonatas CD <jonatas.cd@gmail.com>
Date: Mon, 4 Sep 2017 21:43:29 +0200
Subject: [PATCH] Fixed #28479 -- Doc'd that transaction rollback doesn't
 revert model state.

---
 docs/topics/db/transactions.txt | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/topics/db/transactions.txt b/docs/topics/db/transactions.txt
index 7ada3948ce..eb2b02046c 100644
--- a/docs/topics/db/transactions.txt
+++ b/docs/topics/db/transactions.txt
@@ -176,6 +176,29 @@ Django provides a single API to control database transactions.
         If you catch exceptions raised by raw SQL queries, Django's behavior
         is unspecified and database-dependent.
 
+    .. admonition:: You may need to manually revert model state when rolling back a transaction.
+
+        The values of a model's fields won't be reverted when a transaction
+        rollback happens. This could lead to an inconsistent model state unless
+        you manually restore the original field values.
+
+        For example, given ``MyModel`` with an ``active`` field, this snippet
+        ensures that the ``if obj.active`` check at the end uses the correct
+        value if updating ``active`` to ``True`` fails in the transaction::
+
+            from django.db import DatabaseError, transaction
+
+            obj = MyModel(active=False)
+            obj.active = True
+            try:
+                with transaction.atomic():
+                    obj.save()
+            except DatabaseError:
+                obj.active = False
+
+            if obj.active:
+                ...
+
     In order to guarantee atomicity, ``atomic`` disables some APIs. Attempting
     to commit, roll back, or change the autocommit state of the database
     connection within an ``atomic`` block will raise an exception.