Clarify .build() issue with Django>1.8 (Ref #198).

From 1.8 onwards, this crashes:

>>> a = MyModel()  # Don't save
>>> b = MyOtherModel(fkey_to_mymodel=a)

In turn, it breaks:

    class MyModelFactory(factory.django.DjangoModelFactory):
        class Meta:
            model = MyModel

    class MyOtherModelFactory(factory.django.DjangoModelFactory):
        class Meta:
            model = MyOtherModel
        fkey_to_mymodel = factory.SubFactory(MyModelFactory)

    MyOtherModelFactory.build()  # Breaks

The error message is: Cannot assign "MyModel()": "MyModel" instance isn't saved in the database.

See https://code.djangoproject.com/ticket/10811 for details.

1 files changed, 8 insertions, 0 deletions

diff --git a/docs/orms.rst b/docs/orms.rst
index 5105e66..bbe91e6 100644
--- a/docs/orms.rst
+++ b/docs/orms.rst
@@ -40,6 +40,14 @@ All factories for a Django :class:`~django.db.models.Model` should use the
       once all post-generation hooks have run.
 
 
+.. note:: Starting with Django 1.8, it is no longer possible to call ``.build()``
+          on a factory if this factory uses a :class:`~factory.SubFactory` pointing
+          to another model: Django refuses to set a :class:`~djang.db.models.ForeignKey`
+          to an unsaved :class:`~django.db.models.Model` instance.
+
+          See https://code.djangoproject.com/ticket/10811 for details.
+
+
 .. class:: DjangoOptions(factory.base.FactoryOptions)
 
     The ``class Meta`` on a :class:`~DjangoModelFactory` supports extra parameters: