[1.8.x] Fixed #24486 -- Documented method to provide output_field to mixed F expressions

Backport of 820381d38bc02ea8b92837ce869e7332a7db9913 from master

1 files changed, 11 insertions, 0 deletions

diff --git a/docs/ref/models/expressions.txt b/docs/ref/models/expressions.txt
index 0224a21e54..ef319d5d10 100644
--- a/docs/ref/models/expressions.txt
+++ b/docs/ref/models/expressions.txt
@@ -278,6 +278,17 @@ should define the desired ``output_field``. For example, adding an
 ``IntegerField()`` and a ``FloatField()`` together should probably have
 ``output_field=FloatField()`` defined.
 
+.. note::
+
+    When you need to define the ``output_field`` for ``F`` expression
+    arithmetic between different types, it's necessary to surround the
+    expression in another expression::
+
+        from django.db.models import DateTimeField, ExpressionNode, F
+
+        Race.objects.annotate(finish=ExpressionNode(
+            F('start') + F('duration'), output_field=DateTimeField()))
+
 .. versionchanged:: 1.8
 
     ``output_field`` is a new parameter.