[1.8.x] Fixed #24325 -- Documented change in ModelForm.save() foreign key access.

Backport of 0af3822dc362b6253bda1c9699466dd0bbbf6066 from master

2 files changed, 23 insertions, 0 deletions

diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt
index 251680793c..ff3683a4b0 100644
--- a/docs/releases/1.8.txt
+++ b/docs/releases/1.8.txt
@@ -710,6 +710,28 @@ Now, an error will be raised to prevent data loss::
     ...
     ValueError: Cannot assign "<Author: John>": "Author" instance isn't saved in the database.
 
+Accessing foreign keys in ``ModelForm.save()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In older versions, you could access unsaved foreign key objects in
+``ModelForm.save()`` when adding new objects. For example, given ``Book`` with
+a ``ForeignKey`` to ``Author``::
+
+    class BookForm(forms.ModelForm):
+        def save(self, *args, **kwargs):
+            book = super(BookForm, self).save(*args, **kwargs)
+            book.title = "%s by %s" % (book.title, book.author.name)
+            return book
+
+Now if the related instance hasn't been saved (for example, when adding an
+author and some inlined books in the admin), accessing the foreign key
+``book.author`` in the example) will raise ``RelatedObjectDoesNotExist``. This
+change was necessary to avoid assigning unsaved objects to relations (as
+described in the previous section).
+
+To adapt the example above, you could replace ``book.author.name`` with
+``self.cleaned_data['author'].name``.
+
 Management commands that only accept positional arguments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist
index 7efc687e17..6c738c5000 100644
--- a/docs/spelling_wordlist
+++ b/docs/spelling_wordlist
@@ -295,6 +295,7 @@ ing
 ini
 init
 inline
+inlined
 inlines
 inspectdb
 Instagram